codemini-cli 0.2.8 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codemini-cli",
-  "version": "0.2.8",
+  "version": "0.3.0",
   "description": "Coding CLI optimized for small-model workflows and Windows PowerShell",
   "keywords": [
     "cli",

package/src/cli.js

@@ -4,7 +4,7 @@ import { handleConfig } from './commands/config.js';
 import { handleDoctor } from './commands/doctor.js';
 import { handleSkill } from './commands/skill.js';
 
-const VERSION = '0.2.8';
+const VERSION = '0.3.0';
 
 function printHelp() {
   console.log(`codemini ${VERSION}

package/src/core/agent-loop.js

@@ -406,6 +406,161 @@ export function trimInline(value, maxLen = 72) {
   return `${s.slice(0, maxLen - 3)}...`;
 }
 
+function normalizeAssistantText(value) {
+  return String(value || '').trim();
+}
+
+function hasTrailingToolContext(messages = []) {
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const message = messages[index];
+    if (!message || typeof message !== 'object') continue;
+    if (message.role === 'tool') return true;
+    if (message.role === 'assistant' || message.role === 'user') return false;
+  }
+  return false;
+}
+
+function isGenericCompletionText(text) {
+  const normalized = normalizeAssistantText(text).toLowerCase();
+  if (!normalized) return false;
+  const genericPhrases = new Set([
+    'done',
+    'completed',
+    'complete',
+    'finished',
+    'task completed',
+    'all done',
+    'ok',
+    'okay',
+    '已完成',
+    '已完成任务',
+    '完成',
+    '任务完成'
+  ]);
+  return genericPhrases.has(normalized);
+}
+
+function shouldAskForConcreteFinalAnswer(text, messages = []) {
+  if (!hasTrailingToolContext(messages)) return false;
+  const normalized = normalizeAssistantText(text);
+  if (!normalized) return true;
+  return isGenericCompletionText(normalized);
+}
+
+function isBroadRepositoryAnalysisTask(text) {
+  const normalized = String(text || '').trim().toLowerCase();
+  if (!normalized) return false;
+  return (
+    /optimi|improve|analy[sz]e|audit|review|overview|architecture|codebase|repository|repo/.test(normalized) ||
+    /项目.*优化|项目.*问题|可优化|分析这个项目|看看.*项目|代码库|仓库/.test(String(text || ''))
+  );
+}
+
+function parseProjectIndexSummary(text) {
+  const sourceRoots = [];
+  const entryCandidates = [];
+  const candidateFiles = [];
+  for (const line of String(text || '').split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith('source_roots:')) {
+      sourceRoots.push(
+        ...String(trimmed.slice('source_roots:'.length))
+          .split(',')
+          .map((value) => value.trim())
+          .filter(Boolean)
+      );
+    } else if (trimmed.startsWith('entry_candidates:')) {
+      entryCandidates.push(
+        ...String(trimmed.slice('entry_candidates:'.length))
+          .split(',')
+          .map((value) => value.trim())
+          .filter(Boolean)
+      );
+    } else if (trimmed.startsWith('- ')) {
+      const match = trimmed.match(/^- ([^ ]+)/);
+      if (match?.[1]) candidateFiles.push(match[1].trim());
+    }
+  }
+  return { sourceRoots, entryCandidates, candidateFiles };
+}
+
+function createAnalysisGuardState(userPrompt) {
+  return {
+    active: isBroadRepositoryAnalysisTask(userPrompt),
+    indexQueried: false,
+    sourceRoots: new Set(),
+    entryCandidates: new Set(),
+    candidateFiles: new Set(),
+    relevantSourceReads: new Set(),
+    blockedExplorations: 0
+  };
+}
+
+function topLevelPath(value) {
+  const normalized = String(value || '').replace(/\\/g, '/').replace(/^\.\/+/, '').trim();
+  return normalized.split('/')[0] || '';
+}
+
+function isRelevantSourcePath(filePath, state) {
+  const normalized = String(filePath || '').replace(/\\/g, '/').trim();
+  if (!normalized) return false;
+  if (state.candidateFiles.has(normalized) || state.entryCandidates.has(normalized)) return true;
+  for (const root of state.sourceRoots) {
+    if (normalized === root || normalized.startsWith(`${root}/`)) return true;
+  }
+  return false;
+}
+
+function blockedExplorationReason(toolName, args, state) {
+  if (!state.active) return '';
+  if (!state.indexQueried && toolName !== 'query_project_index') {
+    return 'Use query_project_index before broad repository exploration so the next reads stay focused on relevant source files.';
+  }
+
+  const target = String(args?.path || args?.pattern || args?.query || '').replace(/\\/g, '/').trim();
+  const top = topLevelPath(target);
+  if (!top) return '';
+
+  if (['skills', 'souls', 'templates', '.codemini', '.codemini-project'].includes(top)) {
+    return `Skip ${top}/ for broad repository analysis unless the user explicitly asks for it. Inspect relevant source files first.`;
+  }
+  if (top === 'tests' && state.relevantSourceReads.size < 2) {
+    return 'Inspect the next relevant source files before reading tests. Broad analysis should be grounded in production code first.';
+  }
+  return '';
+}
+
+function noteAnalysisEvidence(state, toolName, args, toolResult) {
+  if (!state.active) return;
+  if (toolName === 'query_project_index') {
+    state.indexQueried = true;
+    const summary = parseProjectIndexSummary(JSON.stringify(toolResult));
+    for (const root of summary.sourceRoots) state.sourceRoots.add(root);
+    for (const entry of summary.entryCandidates) state.entryCandidates.add(entry);
+    for (const file of summary.candidateFiles) state.candidateFiles.add(file);
+    const projectMap = toolResult?.project_map || {};
+    for (const root of projectMap.source_roots || []) state.sourceRoots.add(String(root));
+    for (const entry of projectMap.entry_candidates || []) state.entryCandidates.add(String(entry));
+    for (const match of toolResult?.matches || []) {
+      if (match?.file) state.candidateFiles.add(String(match.file));
+    }
+    return;
+  }
+
+  if (toolName === 'read') {
+    const filePath = String(toolResult?.path || args?.path || '').split(':')[0];
+    if (isRelevantSourcePath(filePath, state)) {
+      state.relevantSourceReads.add(filePath);
+    }
+  }
+}
+
+function needsMoreAnalysisEvidence(state) {
+  if (!state.active) return false;
+  if (!state.indexQueried) return true;
+  return state.relevantSourceReads.size < 2;
+}
+
 function normalizeToolCallName(name) {
   return String(name || '').trim();
 }
@@ -509,6 +664,8 @@ export async function runAgentLoop({
 
   let finalText = '';
   let lastAssistantText = '';
+  let pendingSummaryNudges = 0;
+  const analysisGuard = createAnalysisGuardState(userPrompt);
   const alwaysAllowSet = new Set((Array.isArray(alwaysAllowTools) ? alwaysAllowTools : []).map((t) => String(t)));
 
   // Mutable tool list — grows as tool_search loads deferred tools
@@ -522,6 +679,10 @@ export async function runAgentLoop({
       tools: activeTools
     });
 
+    if (completion?.incomplete) {
+      continue;
+    }
+
     const toolCalls = Array.isArray(completion.toolCalls) ? completion.toolCalls : [];
     const assistantText = completion.text || '';
     lastAssistantText = assistantText || lastAssistantText;
@@ -546,10 +707,30 @@ export async function runAgentLoop({
     }
 
     if (toolCalls.length === 0) {
+      if (needsMoreAnalysisEvidence(analysisGuard) && pendingSummaryNudges < 2) {
+        pendingSummaryNudges += 1;
+        messages.push({
+          role: 'user',
+          content:
+            'You have not inspected enough relevant source files yet. Query the project index if needed, then inspect the next relevant source files before concluding. Do not stop after unrelated directories, tests, skills, souls, or templates.'
+        });
+        continue;
+      }
+      if (shouldAskForConcreteFinalAnswer(assistantText, messages.slice(0, -1)) && pendingSummaryNudges < 2) {
+        pendingSummaryNudges += 1;
+        messages.push({
+          role: 'user',
+          content:
+            'You have already inspected tool results. Before stopping, check whether the task is actually complete. If it is, provide a concise final answer with specific findings or concrete next steps. If it is not, continue with the next tool call.'
+        });
+        continue;
+      }
       finalText = assistantText;
       return { text: finalText, messages, steps: step + 1 };
     }
 
+    pendingSummaryNudges = 0;
+
     if (executionMode === 'plan') {
       const plannedLines = callsToPlanSummary(toolCalls);
       finalText = [
@@ -615,6 +796,20 @@ export async function runAgentLoop({
         throw new Error(`Unknown tool: ${call.name}`);
       }
 
+      const blockedReason = blockedExplorationReason(toolName, args, analysisGuard);
+      if (blockedReason) {
+        analysisGuard.blockedExplorations += 1;
+        const content = clipToolResult({ error: blockedReason }, toolResultMaxChars);
+        if (onEvent) {
+          onEvent({ type: 'tool:error', name: displayName, id: call.id, arguments: args, durationMs: 0, summary: trimInline(blockedReason, 120) });
+        }
+        return {
+          callId: call.id,
+          content,
+          error: true
+        };
+      }
+
       let toolResult;
       try {
         toolResult = await handler(args);
@@ -638,6 +833,7 @@ export async function runAgentLoop({
 
       // P1b: Use per-tool formatter if available, else fallback
       let formatted = formatToolResult(toolResult, toolName, args, toolFormatters, toolResultMaxChars);
+      noteAnalysisEvidence(analysisGuard, toolName, args, toolResult);
 
       // P2: If tool_search loaded deferred tools, inject their schemas into activeTools
       if (toolName === 'tool_search' && toolResult && Array.isArray(toolResult.schemas)) {

package/src/core/chat-runtime.js

@@ -1518,7 +1518,7 @@ async function askModel({
 
   const projectContextSnippet = await buildProjectContextSnippet(process.cwd(), text).catch(() => '');
   const effectiveSystemPrompt = projectContextSnippet
-    ? `${systemPrompt}\n\n${projectContextSnippet}\n\nUse this project context as lightweight guidance. Prefer tools for fresh verification before assuming details.`
+    ? `${systemPrompt}\n\n${projectContextSnippet}\n\nUse this project context as lightweight guidance. Query the project index before broad globs or reading many files, then use targeted reads for fresh verification.`
     : systemPrompt;
 
   const { definitions, handlers, formatters, deferredDefinitions } = getBuiltinTools({
@@ -1586,8 +1586,15 @@ async function askModel({
     toolFormatters: formatters,
     deferredDefinitions,
     requestCompletion: async ({ messages, tools, model: selectedModel }) => {
-      if (onAgentEvent) onAgentEvent({ type: 'assistant:start' });
-      return createChatCompletionStream({
+      let started = false;
+      const startAssistantStream = () => {
+        if (!started && onAgentEvent) {
+          started = true;
+          onAgentEvent({ type: 'assistant:start' });
+        }
+      };
+
+      const result = await createChatCompletionStream({
         baseUrl: config.gateway.base_url,
         apiKey: config.gateway.api_key,
         model: selectedModel,
@@ -1596,12 +1603,20 @@ async function askModel({
         timeoutMs: config.gateway.timeout_ms || 90000,
         maxRetries: config.gateway.max_retries ?? 2,
         onTextDelta: (delta) => {
+          startAssistantStream();
           if (onAgentEvent) onAgentEvent({ type: 'assistant:delta', text: delta });
         },
         onToolCallDelta: (toolCall) => {
+          startAssistantStream();
           if (onAgentEvent) onAgentEvent({ type: 'assistant:tool_call_delta', toolCall });
         }
       });
+
+      if (!started && !result?.incomplete && (result?.text || result?.toolCalls?.length)) {
+        startAssistantStream();
+      }
+
+      return result;
     }
   });
 

package/src/core/default-system-prompt.js

@@ -14,8 +14,8 @@ If the user mentions a project-relative path like src/app.ts, resolve it from ${
 
 1. File discovery then read
 User: compare the auth flow
-Assistant: first locate the relevant files
-Tool: glob({"pattern":"src/**/*auth*.ts"})
+Assistant: first narrow the search with the project index
+Tool: query_project_index({"query":"auth flow","path":"src","max_results":3})
 Tool: read({"file_path":"${cwd}/src/auth/service.ts"})
 
 2. Targeted search then exact text edit

package/src/core/project-index.js

@@ -3,7 +3,25 @@ import path from 'node:path';
 import crypto from 'node:crypto';
 import { getFileIndexPath, getProjectIndexDir, getProjectMapPath, getProjectWorkspaceDir } from './paths.js';
 
-const SKIP_DIRS = new Set(['.git', 'node_modules', '.codemini', '.codemini-project', '.codemini-global', 'dist', 'coverage']);
+const SKIP_DIRS = new Set([
+  '.git',
+  'node_modules',
+  '.codemini',
+  '.codemini-project',
+  '.codemini-global',
+  'dist',
+  'coverage',
+  'sessions',
+  'tmp',
+  'temp',
+  '.cache',
+  '.turbo',
+  '.next',
+  'build',
+  'out',
+  'logs',
+  'artifacts'
+]);
 const PROJECT_MARKER_FILES = new Set([
   'package.json',
   'tsconfig.json',
@@ -115,9 +133,9 @@ function gitignorePatternToRegex(pattern) {
   return new RegExp(`^${regexBody}$`);
 }
 
-async function readGitignoreRules(cwd) {
+async function readIgnoreFileRules(cwd, fileName) {
   try {
-    const raw = await fs.readFile(path.join(cwd, '.gitignore'), 'utf8');
+    const raw = await fs.readFile(path.join(cwd, fileName), 'utf8');
     return raw
       .split(/\r?\n/)
       .map((line) => line.trim())
@@ -143,6 +161,18 @@ async function readGitignoreRules(cwd) {
   }
 }
 
+async function readProjectIgnoreRules(cwd) {
+  const [gitignoreRules, llmignoreRules] = await Promise.all([
+    readIgnoreFileRules(cwd, '.gitignore'),
+    readIgnoreFileRules(cwd, '.llmignore')
+  ]);
+  return {
+    gitignoreRules,
+    llmignoreRules,
+    combinedRules: [...gitignoreRules, ...llmignoreRules]
+  };
+}
+
 function matchesGitignoreRule(rule, relativePath, isDirectory) {
   if (!rule || !relativePath) return false;
   if (rule.dirOnly && !isDirectory) return false;
@@ -212,17 +242,17 @@ async function findNearestIndexedProjectRoot(startDir, workspaceRoot) {
   return null;
 }
 
-async function walkFiles(cwd, start = cwd, out = [], gitignoreRules = []) {
+async function walkFiles(cwd, start = cwd, out = [], ignoreRules = []) {
   const entries = await fs.readdir(start, { withFileTypes: true });
   for (const entry of entries) {
     const absolutePath = path.join(start, entry.name);
     const relativePath = rel(cwd, absolutePath);
     if (entry.isDirectory()) {
-      if (shouldIgnorePath(relativePath, true, gitignoreRules)) continue;
-      await walkFiles(cwd, absolutePath, out, gitignoreRules);
+      if (shouldIgnorePath(relativePath, true, ignoreRules)) continue;
+      await walkFiles(cwd, absolutePath, out, ignoreRules);
       continue;
     }
-    if (shouldIgnorePath(relativePath, false, gitignoreRules)) continue;
+    if (shouldIgnorePath(relativePath, false, ignoreRules)) continue;
     out.push(absolutePath);
   }
   return out;
@@ -298,12 +328,12 @@ async function scanProject(cwd) {
       workspaceKind,
       projectMap: null,
       fileIndex: null,
-      gitignoreRules: []
+      ignoreRules: []
     };
   }
 
-  const gitignoreRules = await readGitignoreRules(cwd);
-  const allFiles = await walkFiles(cwd, cwd, [], gitignoreRules);
+  const { gitignoreRules, llmignoreRules, combinedRules } = await readProjectIgnoreRules(cwd);
+  const allFiles = await walkFiles(cwd, cwd, [], combinedRules);
   const relativeFiles = allFiles.map((filePath) => rel(cwd, filePath));
   const sourceFiles = allFiles.filter((filePath) => SOURCE_EXTENSIONS.has(path.extname(filePath).toLowerCase()));
 
@@ -362,13 +392,14 @@ async function scanProject(cwd) {
       frameworkHints,
       directories,
       gitignoreEnabled: gitignoreRules.length > 0,
+      llmignoreEnabled: llmignoreRules.length > 0,
       updatedAt: new Date().toISOString()
     },
     fileIndex: {
       updatedAt: new Date().toISOString(),
       files
     },
-    gitignoreRules
+    ignoreRules: combinedRules
   };
 }
 
@@ -417,7 +448,7 @@ export async function refreshIndexedFile(cwd = process.cwd(), relativePath = '')
   const projectRoot = await findProjectRootFromFile(cwd, relativePath);
   if (!projectRoot) return null;
   const fileIndexPath = getFileIndexPath(projectRoot);
-  const gitignoreRules = await readGitignoreRules(projectRoot);
+  const { combinedRules } = await readProjectIgnoreRules(projectRoot);
   const absolutePath = path.join(cwd, relativePath);
   const stat = await safeStat(absolutePath);
   let action = 'updated';
@@ -426,7 +457,7 @@ export async function refreshIndexedFile(cwd = process.cwd(), relativePath = '')
   const files = Array.isArray(current.files) ? [...current.files] : [];
   const index = files.findIndex((entry) => entry.file === projectRelativePath);
 
-  if (shouldIgnorePath(projectRelativePath, Boolean(stat?.isDirectory?.()), gitignoreRules)) {
+  if (shouldIgnorePath(projectRelativePath, Boolean(stat?.isDirectory?.()), combinedRules)) {
     if (index >= 0) files.splice(index, 1);
     action = 'removed';
   } else if (!stat || !stat.isFile()) {
@@ -508,3 +539,99 @@ export async function buildProjectContextSnippet(cwd = process.cwd(), userText =
   const snippet = trimMultiline(lines.join('\n'));
   return snippet;
 }
+
+export async function queryProjectIndex(cwd = process.cwd(), args = {}) {
+  const indexedRoot = await findNearestIndexedProjectRoot(cwd, cwd);
+  if (!indexedRoot) {
+    return {
+      query: String(args?.query || '').trim(),
+      project_root: '',
+      project_map: null,
+      matches: []
+    };
+  }
+
+  const projectMap = await safeReadJson(getProjectMapPath(indexedRoot), null);
+  const fileIndex = await safeReadJson(getFileIndexPath(indexedRoot), null);
+  const query = String(args?.query || '').trim();
+  const pathPrefix = normalizeRelativePath(args?.path || args?.path_prefix || '');
+  const languageFilter = String(args?.language || '').trim().toLowerCase();
+  const maxResults = Math.max(1, Math.min(20, Number(args?.max_results || 8) || 8));
+  const files = Array.isArray(fileIndex?.files) ? fileIndex.files : [];
+  const tokens = tokenizeQuery(query);
+
+  const matches = [];
+  for (const entry of files) {
+    const relativePath = String(entry?.file || '');
+    if (!relativePath) continue;
+    if (pathPrefix && !relativePath.startsWith(pathPrefix)) continue;
+    if (languageFilter && String(entry?.language || '').toLowerCase() !== languageFilter) continue;
+
+    let score = 0;
+    const reasons = [];
+    const fileText = relativePath.toLowerCase();
+    for (const token of tokens) {
+      if (!token) continue;
+      if (fileText.includes(token)) {
+        score += 5;
+        reasons.push(`path:${token}`);
+      }
+      if ((entry.exports || []).some((value) => String(value).toLowerCase() === token)) {
+        score += 4;
+        reasons.push(`export:${token}`);
+      }
+      if ((entry.functions || []).some((value) => String(value).toLowerCase().includes(token))) {
+        score += 4;
+        reasons.push(`function:${token}`);
+      }
+      if ((entry.classes || []).some((value) => String(value).toLowerCase().includes(token))) {
+        score += 4;
+        reasons.push(`class:${token}`);
+      }
+      if ((entry.imports || []).some((value) => String(value).toLowerCase().includes(token))) {
+        score += 2;
+        reasons.push(`import:${token}`);
+      }
+    }
+
+    if (!query) {
+      if ((projectMap?.entryCandidates || []).includes(relativePath)) score += 3;
+      if ((projectMap?.importantFiles || []).includes(relativePath)) score += 2;
+      if (String(relativePath).startsWith('src/')) score += 1;
+    }
+
+    if (score <= 0 && query) continue;
+    matches.push({
+      file: relativePath,
+      language: entry.language || 'text',
+      score,
+      reasons: clipList(reasons, 8),
+      exports: clipList(entry.exports || [], 6),
+      functions: clipList(entry.functions || [], 6),
+      classes: clipList(entry.classes || [], 6),
+      imports: clipList(entry.imports || [], 6)
+    });
+  }
+
+  matches.sort((left, right) => right.score - left.score || String(left.file).localeCompare(String(right.file)));
+
+  return {
+    query,
+    project_root: indexedRoot,
+    project_map: projectMap
+      ? {
+          workspace_kind: projectMap.workspaceKind || 'project',
+          languages: clipList(projectMap.languages || [], 8),
+          package_managers: clipList(projectMap.packageManagers || [], 8),
+          important_files: clipList(projectMap.importantFiles || [], 8),
+          source_roots: clipList(projectMap.sourceRoots || [], 8),
+          test_roots: clipList(projectMap.testRoots || [], 8),
+          entry_candidates: clipList(projectMap.entryCandidates || [], 8),
+          framework_hints: clipList(projectMap.frameworkHints || [], 8),
+          gitignore_enabled: Boolean(projectMap.gitignoreEnabled),
+          llmignore_enabled: Boolean(projectMap.llmignoreEnabled)
+        }
+      : null,
+    matches: matches.slice(0, maxResults)
+  };
+}

package/src/core/provider/openai-compatible.js

@@ -145,13 +145,15 @@ function buildFinalStreamResult(text, toolCallsByIndex, usage, messages) {
       arguments: tc.arguments || '{}'
     }))
     .filter((tc) => tc.name);
+  const normalizedText = String(text || '').trim();
 
-  if (!text && toolCalls.length === 0) {
+  if (!normalizedText && toolCalls.length === 0) {
     if (hasTrailingToolContext(messages)) {
       return {
         text: '',
         toolCalls: [],
-        usage
+        usage,
+        incomplete: true
       };
     }
     throw new Error('Gateway stream returned empty assistant response');
@@ -160,7 +162,8 @@ function buildFinalStreamResult(text, toolCallsByIndex, usage, messages) {
   return {
     text,
     toolCalls,
-    usage
+    usage,
+    incomplete: false
   };
 }
 
@@ -246,8 +249,17 @@ export async function createChatCompletion({
     name: tc.function?.name,
     arguments: normalizeIncomingToolCallArguments(tc.function?.arguments)
   }));
+  const normalizedText = String(text || '').trim();
 
-  if (!text && toolCalls.length === 0) {
+  if (!normalizedText && toolCalls.length === 0) {
+    if (hasTrailingToolContext(messages)) {
+      return {
+        text: '',
+        toolCalls: [],
+        usage: data?.usage || null,
+        incomplete: true
+      };
+    }
     throw new Error('Gateway returned empty assistant response');
   }
 

package/src/core/shell-profile.js

@@ -123,6 +123,7 @@ export function getShellSystemPrompt(value) {
 # Using your tools
 
 ALWAYS prefer dedicated tools over raw shell commands:
+- Use query_project_index first for broad repository understanding. It combines project-map metadata with indexed file symbols so you can narrow candidates before reading source files
 - Use read to inspect files — NEVER use cat, head, or tail via run. read returns content directly by default; demo-style shapes like {file_path:"src/app.ts"}, {path:"src/app.ts:10-40"}, or {file_path:"src/app.ts", offset:10, limit:30} are accepted
 - Use grep to search file contents — NEVER use grep or rg via run
 - Use glob to find files by pattern — NEVER use find via run
@@ -141,6 +142,7 @@ For services: use start_service to launch, list_services/get_service_status/get_
 Some tools are loaded on demand. If a needed tool is not listed, call tool_search first to load it.
 
 Common tool call patterns:
+- Query the project index first: {query:"login auth flow", path:"src", max_results:5}
 - Read a file: {path:"src/app.ts"} or {file_path:"src/app.ts", offset:20, limit:40}
 - Read a specific range inline: {path:"src/app.ts:20-60"}
 - Search text: {pattern:"loginUser", path:"src"} or {query:"loginUser", directory:"src"}
@@ -158,6 +160,8 @@ Common tool call patterns:
 - Before substantial tool work, send a short progress update to the user about what you are about to inspect or do
 - Do not jump straight into tools without a brief user-facing note when the task is actionable
 - Search or read before editing unless the exact target is already known
+- For broad or ambiguous requests, query_project_index before large globs or reading many files
+- Do not read files one by one after a wide glob when query_project_index can narrow the candidates first
 - If a command or tool is blocked or fails, inspect the error and retry with allowed commands or tools
 - For AST-scoped edits, if edit rejects due to missing or stale ast_target, fix arguments and retry
 - Do not claim filesystem access is impossible unless search/read tools also fail