@contextstream/mcp-server 0.4.67 → 0.4.71

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

@@ -67,6 +67,8 @@ function getOrCreateEntry(state, cwd) {
     require_init: false,
     last_context_at: void 0,
     last_state_change_at: void 0,
+    index_wait_started_at: void 0,
+    index_wait_until: void 0,
     updated_at: nowIso()
   };
   state.workspaces[cwd] = created;
@@ -96,6 +98,8 @@ function clearContextRequired(cwd) {
   if (!target) return;
   target.entry.require_context = false;
   target.entry.last_context_at = nowIso();
+  target.entry.index_wait_started_at = void 0;
+  target.entry.index_wait_until = void 0;
   target.entry.updated_at = nowIso();
   writeState(state);
 }
@@ -147,6 +151,44 @@ function isContextFreshAndClean(cwd, maxAgeSeconds) {
   }
   return true;
 }
+function startIndexWaitWindow(cwd, waitSeconds) {
+  if (!cwd.trim() || waitSeconds <= 0) return;
+  const state = readState();
+  const target = getOrCreateEntry(state, cwd);
+  if (!target) return;
+  const now = Date.now();
+  const existingUntil = target.entry.index_wait_until ? new Date(target.entry.index_wait_until).getTime() : NaN;
+  if (!Number.isNaN(existingUntil) && existingUntil > now) {
+    target.entry.updated_at = nowIso();
+    writeState(state);
+    return;
+  }
+  target.entry.index_wait_started_at = new Date(now).toISOString();
+  target.entry.index_wait_until = new Date(now + waitSeconds * 1e3).toISOString();
+  target.entry.updated_at = nowIso();
+  writeState(state);
+}
+function clearIndexWaitWindow(cwd) {
+  if (!cwd.trim()) return;
+  const state = readState();
+  const target = getOrCreateEntry(state, cwd);
+  if (!target) return;
+  target.entry.index_wait_started_at = void 0;
+  target.entry.index_wait_until = void 0;
+  target.entry.updated_at = nowIso();
+  writeState(state);
+}
+function indexWaitRemainingSeconds(cwd) {
+  if (!cwd.trim()) return null;
+  const state = readState();
+  const target = getOrCreateEntry(state, cwd);
+  if (!target?.entry.index_wait_until) return null;
+  const until = new Date(target.entry.index_wait_until).getTime();
+  if (Number.isNaN(until)) return null;
+  const remainingMs = until - Date.now();
+  if (remainingMs <= 0) return null;
+  return Math.ceil(remainingMs / 1e3);
+}
 
 // src/hooks/pre-tool-use.ts
 var ENABLED = process.env.CONTEXTSTREAM_HOOK_ENABLED !== "false";
@@ -154,6 +196,9 @@ var INDEX_STATUS_FILE = path2.join(homedir2(), ".contextstream", "indexed-projec
 var DEBUG_FILE = "/tmp/pretooluse-hook-debug.log";
 var STALE_THRESHOLD_DAYS = 7;
 var CONTEXT_FRESHNESS_SECONDS = 120;
+var DEFAULT_INDEX_WAIT_SECONDS = 20;
+var MIN_INDEX_WAIT_SECONDS = 15;
+var MAX_INDEX_WAIT_SECONDS = 20;
 var DISCOVERY_PATTERNS = ["**/*", "**/", "src/**", "lib/**", "app/**", "components/**"];
 function isDiscoveryGlob(pattern) {
   const patternLower = pattern.toLowerCase();
@@ -179,6 +224,33 @@ function isDiscoveryGrep(filePath) {
   }
   return false;
 }
+function configuredIndexWaitSeconds() {
+  const parsed = Number.parseInt(process.env.CONTEXTSTREAM_INDEX_WAIT_SECONDS ?? "", 10);
+  if (Number.isNaN(parsed)) return DEFAULT_INDEX_WAIT_SECONDS;
+  return Math.min(MAX_INDEX_WAIT_SECONDS, Math.max(MIN_INDEX_WAIT_SECONDS, parsed));
+}
+function isLocalDiscoveryToolDuringIndexWait(tool, toolInput) {
+  if (tool === "Glob" || tool === "Explore" || tool === "SemanticSearch" || tool === "codebase_search") {
+    return true;
+  }
+  if (tool === "Task") {
+    const subagentTypeRaw = toolInput?.subagent_type || toolInput?.subagentType || "";
+    return subagentTypeRaw.toLowerCase().includes("explore");
+  }
+  if (tool === "Grep" || tool === "Search" || tool === "grep_search" || tool === "code_search") {
+    const filePath = toolInput?.path || "";
+    return isDiscoveryGrep(filePath);
+  }
+  if (tool === "Read" || tool === "ReadFile" || tool === "read_file") {
+    const filePath = toolInput?.file_path || toolInput?.path || toolInput?.file || toolInput?.target_file || "";
+    return isDiscoveryGrep(filePath);
+  }
+  if (tool === "list_files" || tool === "search_files" || tool === "search_files_content" || tool === "find_files" || tool === "find_by_name") {
+    const pattern = toolInput?.path || toolInput?.regex || toolInput?.pattern || toolInput?.query || "";
+    return !pattern || isDiscoveryGlob(pattern) || isDiscoveryGrep(pattern);
+  }
+  return false;
+}
 function isProjectIndexed(cwd) {
   if (!fs2.existsSync(INDEX_STATUS_FILE)) {
     return { isIndexed: false, isStale: false };
@@ -440,12 +512,22 @@ async function runPreToolUseHook() {
       blockWithMessage(editorFormat, msg);
     }
   }
-  const { isIndexed } = isProjectIndexed(cwd);
-  fs2.appendFileSync(DEBUG_FILE, `[PreToolUse] isIndexed=${isIndexed}
-`);
-  if (!isIndexed) {
-    fs2.appendFileSync(DEBUG_FILE, `[PreToolUse] Project not indexed, allowing
+  const { isIndexed, isStale } = isProjectIndexed(cwd);
+  fs2.appendFileSync(DEBUG_FILE, `[PreToolUse] isIndexed=${isIndexed}, isStale=${isStale}
 `);
+  if (isIndexed && !isStale) {
+    clearIndexWaitWindow(cwd);
+  } else {
+    const waitSeconds = configuredIndexWaitSeconds();
+    if (isLocalDiscoveryToolDuringIndexWait(tool, toolInput)) {
+      startIndexWaitWindow(cwd, waitSeconds);
+      const remaining = indexWaitRemainingSeconds(cwd);
+      if (remaining && remaining > 0) {
+        const msg = `Index refresh grace window is active (${remaining}s remaining). Keep ContextStream search-first flow: mcp__contextstream__search(mode="auto", query="..."). Do not use local discovery tools yet for stale/not-indexed projects. Retry after refresh; local fallback is allowed only after ~${waitSeconds}s if index is still unavailable.`;
+        blockWithMessage(editorFormat, msg);
+      }
+      allowTool(editorFormat, cwd, recordStateChange);
+    }
     allowTool(editorFormat, cwd, recordStateChange);
   }
   if (tool === "Glob") {

package/dist/hooks/runner.js

@@ -76,6 +76,8 @@ function getOrCreateEntry(state, cwd) {
     require_init: false,
     last_context_at: void 0,
     last_state_change_at: void 0,
+    index_wait_started_at: void 0,
+    index_wait_until: void 0,
     updated_at: nowIso()
   };
   state.workspaces[cwd] = created;
@@ -114,6 +116,8 @@ function clearContextRequired(cwd) {
   if (!target) return;
   target.entry.require_context = false;
   target.entry.last_context_at = nowIso();
+  target.entry.index_wait_started_at = void 0;
+  target.entry.index_wait_until = void 0;
   target.entry.updated_at = nowIso();
   writeState(state);
 }
@@ -174,6 +178,44 @@ function isContextFreshAndClean(cwd, maxAgeSeconds) {
   }
   return true;
 }
+function startIndexWaitWindow(cwd, waitSeconds) {
+  if (!cwd.trim() || waitSeconds <= 0) return;
+  const state = readState();
+  const target = getOrCreateEntry(state, cwd);
+  if (!target) return;
+  const now = Date.now();
+  const existingUntil = target.entry.index_wait_until ? new Date(target.entry.index_wait_until).getTime() : NaN;
+  if (!Number.isNaN(existingUntil) && existingUntil > now) {
+    target.entry.updated_at = nowIso();
+    writeState(state);
+    return;
+  }
+  target.entry.index_wait_started_at = new Date(now).toISOString();
+  target.entry.index_wait_until = new Date(now + waitSeconds * 1e3).toISOString();
+  target.entry.updated_at = nowIso();
+  writeState(state);
+}
+function clearIndexWaitWindow(cwd) {
+  if (!cwd.trim()) return;
+  const state = readState();
+  const target = getOrCreateEntry(state, cwd);
+  if (!target) return;
+  target.entry.index_wait_started_at = void 0;
+  target.entry.index_wait_until = void 0;
+  target.entry.updated_at = nowIso();
+  writeState(state);
+}
+function indexWaitRemainingSeconds(cwd) {
+  if (!cwd.trim()) return null;
+  const state = readState();
+  const target = getOrCreateEntry(state, cwd);
+  if (!target?.entry.index_wait_until) return null;
+  const until = new Date(target.entry.index_wait_until).getTime();
+  if (Number.isNaN(until)) return null;
+  const remainingMs = until - Date.now();
+  if (remainingMs <= 0) return null;
+  return Math.ceil(remainingMs / 1e3);
+}
 var STATE_PATH;
 var init_prompt_state = __esm({
   "src/hooks/prompt-state.ts"() {
@@ -214,6 +256,33 @@ function isDiscoveryGrep(filePath) {
   }
   return false;
 }
+function configuredIndexWaitSeconds() {
+  const parsed = Number.parseInt(process.env.CONTEXTSTREAM_INDEX_WAIT_SECONDS ?? "", 10);
+  if (Number.isNaN(parsed)) return DEFAULT_INDEX_WAIT_SECONDS;
+  return Math.min(MAX_INDEX_WAIT_SECONDS, Math.max(MIN_INDEX_WAIT_SECONDS, parsed));
+}
+function isLocalDiscoveryToolDuringIndexWait(tool, toolInput) {
+  if (tool === "Glob" || tool === "Explore" || tool === "SemanticSearch" || tool === "codebase_search") {
+    return true;
+  }
+  if (tool === "Task") {
+    const subagentTypeRaw = toolInput?.subagent_type || toolInput?.subagentType || "";
+    return subagentTypeRaw.toLowerCase().includes("explore");
+  }
+  if (tool === "Grep" || tool === "Search" || tool === "grep_search" || tool === "code_search") {
+    const filePath = toolInput?.path || "";
+    return isDiscoveryGrep(filePath);
+  }
+  if (tool === "Read" || tool === "ReadFile" || tool === "read_file") {
+    const filePath = toolInput?.file_path || toolInput?.path || toolInput?.file || toolInput?.target_file || "";
+    return isDiscoveryGrep(filePath);
+  }
+  if (tool === "list_files" || tool === "search_files" || tool === "search_files_content" || tool === "find_files" || tool === "find_by_name") {
+    const pattern = toolInput?.path || toolInput?.regex || toolInput?.pattern || toolInput?.query || "";
+    return !pattern || isDiscoveryGlob(pattern) || isDiscoveryGrep(pattern);
+  }
+  return false;
+}
 function isProjectIndexed(cwd) {
   if (!fs2.existsSync(INDEX_STATUS_FILE)) {
     return { isIndexed: false, isStale: false };
@@ -475,12 +544,22 @@ async function runPreToolUseHook() {
       blockWithMessage(editorFormat, msg);
     }
   }
-  const { isIndexed } = isProjectIndexed(cwd);
-  fs2.appendFileSync(DEBUG_FILE, `[PreToolUse] isIndexed=${isIndexed}
-`);
-  if (!isIndexed) {
-    fs2.appendFileSync(DEBUG_FILE, `[PreToolUse] Project not indexed, allowing
+  const { isIndexed, isStale } = isProjectIndexed(cwd);
+  fs2.appendFileSync(DEBUG_FILE, `[PreToolUse] isIndexed=${isIndexed}, isStale=${isStale}
 `);
+  if (isIndexed && !isStale) {
+    clearIndexWaitWindow(cwd);
+  } else {
+    const waitSeconds = configuredIndexWaitSeconds();
+    if (isLocalDiscoveryToolDuringIndexWait(tool, toolInput)) {
+      startIndexWaitWindow(cwd, waitSeconds);
+      const remaining = indexWaitRemainingSeconds(cwd);
+      if (remaining && remaining > 0) {
+        const msg = `Index refresh grace window is active (${remaining}s remaining). Keep ContextStream search-first flow: mcp__contextstream__search(mode="auto", query="..."). Do not use local discovery tools yet for stale/not-indexed projects. Retry after refresh; local fallback is allowed only after ~${waitSeconds}s if index is still unavailable.`;
+        blockWithMessage(editorFormat, msg);
+      }
+      allowTool(editorFormat, cwd, recordStateChange);
+    }
     allowTool(editorFormat, cwd, recordStateChange);
   }
   if (tool === "Glob") {
@@ -572,7 +651,7 @@ async function runPreToolUseHook() {
   }
   allowTool(editorFormat, cwd, recordStateChange);
 }
-var ENABLED, INDEX_STATUS_FILE, DEBUG_FILE, STALE_THRESHOLD_DAYS, CONTEXT_FRESHNESS_SECONDS, DISCOVERY_PATTERNS, isDirectRun;
+var ENABLED, INDEX_STATUS_FILE, DEBUG_FILE, STALE_THRESHOLD_DAYS, CONTEXT_FRESHNESS_SECONDS, DEFAULT_INDEX_WAIT_SECONDS, MIN_INDEX_WAIT_SECONDS, MAX_INDEX_WAIT_SECONDS, DISCOVERY_PATTERNS, isDirectRun;
 var init_pre_tool_use = __esm({
   "src/hooks/pre-tool-use.ts"() {
     "use strict";
@@ -582,6 +661,9 @@ var init_pre_tool_use = __esm({
     DEBUG_FILE = "/tmp/pretooluse-hook-debug.log";
     STALE_THRESHOLD_DAYS = 7;
     CONTEXT_FRESHNESS_SECONDS = 120;
+    DEFAULT_INDEX_WAIT_SECONDS = 20;
+    MIN_INDEX_WAIT_SECONDS = 15;
+    MAX_INDEX_WAIT_SECONDS = 20;
     DISCOVERY_PATTERNS = ["**/*", "**/", "src/**", "lib/**", "app/**", "components/**"];
     isDirectRun = process.argv[1]?.includes("pre-tool-use") || process.argv[2] === "pre-tool-use";
     if (isDirectRun) {
@@ -1681,23 +1763,22 @@ Returns: \`indexed\` (true/false), \`last_indexed_at\`, \`file_count\`
 \u2192 Use \`search(mode="auto", query="...")\`
 
 **IF indexed=false OR last_indexed_at is stale (>7 days):**
-\u2192 Use local tools (Glob/Grep/Read) directly
-\u2192 OR run \`project(action="index")\` first, then search
+\u2192 Wait up to ~20s for background refresh, retry \`search(mode="auto", query="...")\`
+\u2192 After grace window: local tools are allowed if search still misses
 
-**IF search returns 0 results or errors:**
+**IF search still returns 0 results or errors after retry/window:**
 \u2192 Fallback to local tools (Glob/Grep/Read)
 
 ### \u2705 When Local Tools (Glob/Grep/Read) Are OK:
-- Project is NOT indexed
-- Index is stale/outdated (>7 days)
-- ContextStream search returns 0 results
+- Stale/not-indexed grace window has elapsed (~20s default, configurable)
+- ContextStream search still returns 0 results after retry
 - ContextStream returns errors
 - User explicitly requests local tools
 
 ### On Session Start:
 1. Call \`init(folder_path="...")\` - triggers initial indexing
 2. Check \`project(action="index_status")\` before searching
-3. If not indexed: use local tools OR wait for indexing
+3. If not indexed: wait for background refresh (~20s), retry search, then use local tools only after the grace window
 
 ### After File Changes (Edit/Write/Create):
 Files are NOT auto-indexed. You MUST:
@@ -1832,13 +1913,12 @@ COMMON MEMORY CALLS: list docs via memory(action="list_docs"), list lessons via
 2. FOR CODE SEARCH: Check index status, then search appropriately
    \u26A0\uFE0F BEFORE searching: mcp__contextstream__project(action="index_status")
    \u2705 IF indexed & fresh: Use mcp__contextstream__search(mode="auto", query="...") BEFORE Glob/Grep/Read/Explore/Task/EnterPlanMode
-   \u2705 IF NOT indexed OR stale: Use local tools (Glob/Grep/Read) directly
-   \u2705 IF search returns 0 results: Fallback to local tools (Glob/Grep/Read)
+   \u2705 IF NOT indexed OR stale: wait for background refresh up to ~20s, retry mcp__contextstream__search(mode="auto", query="..."), then allow local tools only after the grace window
+   \u2705 IF search still returns 0 results after retry/window: fallback to local tools (Glob/Grep/Read)
 
 3. WHEN LOCAL TOOLS (Glob/Grep/Read) ARE OK:
-   \u2705 Project is NOT indexed (index_status.indexed=false)
-   \u2705 Index is stale/outdated (>7 days old)
-   \u2705 ContextStream search returns 0 results or errors
+   \u2705 Stale/not-indexed grace window has elapsed (~20s default, configurable)
+   \u2705 ContextStream search still returns 0 results or errors after retry
    \u2705 User explicitly requests local tools
 
 4. FOR PLANS & TASKS: Use ContextStream, not file-based plans
@@ -2540,7 +2620,7 @@ Use \`context()\` by default to get task-specific rules, lessons from past mista
 2. **PreToolUse blocking** - If you try to use Glob/Grep/Search/Explore:
    - Hook returns error: \`STOP: Use mcp__contextstream__search(mode="auto") instead\`
    - **You MUST use the suggested ContextStream tool instead**
-   - Local tools are only allowed if project is not indexed or ContextStream returns 0 results
+  - For stale/not-indexed projects, wait for background refresh (up to ~20s), retry search, then allow local tools only after the grace window
 
 3. **PostToolUse indexing** - After Edit/Write operations:
    - Changed files are automatically re-indexed
@@ -2577,7 +2657,7 @@ STOP \u2192 Call search(mode="auto", query="...") FIRST
 
 \u2705 **ALWAYS DO THIS:**
 1. \`search(mode="auto", query="what you're looking for")\`
-2. Only use local tools (Glob/Grep/Read) if ContextStream returns **0 results**
+2. Only use local tools (Glob/Grep/Read) after stale/not-indexed refresh grace window elapses (~20s) or ContextStream still returns **0 results** after retry
 3. Use Read ONLY for exact file edits after you know the file path
 
 This applies to **EVERY search** throughout the **ENTIRE conversation**, not just the first message.
@@ -2840,7 +2920,7 @@ session(action="capture", event_type="session_snapshot", title="Pre-compaction s
 
 ### Search & Code Intelligence (ContextStream-first)
 
-\u26A0\uFE0F **STOP: Before using Search/Glob/Grep/Read/Explore** \u2192 Call \`search(mode="auto")\` FIRST. Use local tools ONLY if ContextStream returns 0 results.
+\u26A0\uFE0F **STOP: Before using Search/Glob/Grep/Read/Explore** \u2192 Call \`search(mode="auto")\` FIRST. For stale/not-indexed projects, wait ~20s for background refresh and retry search before local fallback.
 
 **\u274C WRONG workflow (wastes tokens, slow):**
 \`\`\`
@@ -2859,7 +2939,7 @@ search(mode="auto", query="function implementation") \u2192 done (results includ
 2. \`search(mode="auto", query="...", limit=3)\` or \`search(mode="keyword", query="<filename>", limit=3)\`
 3. \`project(action="files")\` - file tree/list (only when needed)
 4. \`graph(action="dependencies", ...)\` - code structure
-5. Local repo scans (rg/ls/find) - ONLY if ContextStream returns no results, errors, or the user explicitly asks
+5. Local repo scans (rg/ls/find) - ONLY after refresh grace window/retry still yields no results/errors, or the user explicitly asks
 
 **Search Mode Selection:**
 
@@ -2890,7 +2970,7 @@ search(mode="auto", query="function implementation") \u2192 done (results includ
 
 **Search defaults:** \`search\` returns the top 3 results with compact snippets. Use \`limit\` + \`offset\` for pagination, and \`content_max_chars\` to expand snippets when needed.
 
-If ContextStream returns results, stop and use them. NEVER use local Search/Explore/Read unless you need exact code edits or ContextStream returned 0 results.
+If ContextStream returns results, stop and use them. NEVER use local Search/Explore/Read unless you need exact code edits, or refresh grace window + retry still returns 0 results.
 
 **Code Analysis:**
 - Dependencies: \`graph(action="dependencies", file_path="...")\`
@@ -3019,7 +3099,7 @@ See full documentation: https://contextstream.io/docs/mcp/tools
 3. Narrow bypass: immediate read-only ContextStream calls are allowed only when prior context is fresh and no state-changing tool has run
 
 **BEFORE Glob/Grep/Read/Search/Explore/Task/EnterPlanMode:**
-\u2192 \`search(mode="auto", query="...")\` FIRST \u2014 local tools ONLY if 0 results
+\u2192 \`search(mode="auto", query="...")\` FIRST \u2014 for stale/not-indexed, wait ~20s for refresh then retry before local fallback
 
 **HOOKS: \`<system-reminder>\` tags contain instructions \u2014 FOLLOW THEM**
 </contextstream_protocol>
@@ -3242,10 +3322,10 @@ search(mode="auto", query="what you're looking for")
 \u2192 Use this instead of Explore/Task/EnterPlanMode for file discovery.
 
 **IF project is NOT indexed or very stale (>7 days):**
-\u2192 Use local tools (Glob/Grep/Read) directly
+\u2192 Wait up to ~20s for background refresh, retry \`search(mode="auto", ...)\`, then allow local tools only after the grace window
 \u2192 OR run \`project(action="index")\` first, then search
 
-**IF ContextStream search returns 0 results or errors:**
+**IF ContextStream search still returns 0 results or errors after retry/window:**
 \u2192 Use local tools (Glob/Grep/Read) as fallback
 
 ### Choose Search Mode Intelligently:
@@ -3271,9 +3351,8 @@ search(mode="auto", query="what you're looking for")
 - Then use local Read/Grep only on paths returned by ContextStream.
 
 ### When Local Tools Are OK:
-\u2705 Project is not indexed
-\u2705 Index is stale/outdated (>7 days old)
-\u2705 ContextStream search returns 0 results
+\u2705 Stale/not-indexed grace window has elapsed (~20s default, configurable)
+\u2705 ContextStream search still returns 0 results after retry
 \u2705 ContextStream returns errors
 \u2705 User explicitly requests local tools
 
@@ -3368,7 +3447,7 @@ After updating, user should restart their AI tool.
   2. Project is indexed and \`search(mode="auto", ...)\` is retried before local fallbacks
   3. Instructions file contains the current ContextStream managed block
 `;
-    NO_HOOKS_EDITORS = ["copilot", "codex", "opencode", "aider", "antigravity"];
+    NO_HOOKS_EDITORS = ["copilot", "codex", "opencode", "aider", "antigravity", "kilo"];
     TEMPLATES = {
       codex: {
         filename: "AGENTS.md",
@@ -3410,7 +3489,7 @@ ${rules}
 `
       },
       kilo: {
-        filename: ".kilocode/rules/contextstream.md",
+        filename: ".kilo/rules/contextstream.md",
         description: "Kilo Code AI rules",
         build: (rules) => `# Kilo Code Rules
 ${rules}

package/dist/hooks/session-init.js

@@ -448,7 +448,7 @@ Use \`context()\` by default to get task-specific rules, lessons from past mista
 2. **PreToolUse blocking** - If you try to use Glob/Grep/Search/Explore:
    - Hook returns error: \`STOP: Use mcp__contextstream__search(mode="auto") instead\`
    - **You MUST use the suggested ContextStream tool instead**
-   - Local tools are only allowed if project is not indexed or ContextStream returns 0 results
+  - For stale/not-indexed projects, wait for background refresh (up to ~20s), retry search, then allow local tools only after the grace window
 
 3. **PostToolUse indexing** - After Edit/Write operations:
    - Changed files are automatically re-indexed
@@ -485,7 +485,7 @@ STOP \u2192 Call search(mode="auto", query="...") FIRST
 
 \u2705 **ALWAYS DO THIS:**
 1. \`search(mode="auto", query="what you're looking for")\`
-2. Only use local tools (Glob/Grep/Read) if ContextStream returns **0 results**
+2. Only use local tools (Glob/Grep/Read) after stale/not-indexed refresh grace window elapses (~20s) or ContextStream still returns **0 results** after retry
 3. Use Read ONLY for exact file edits after you know the file path
 
 This applies to **EVERY search** throughout the **ENTIRE conversation**, not just the first message.
@@ -748,7 +748,7 @@ session(action="capture", event_type="session_snapshot", title="Pre-compaction s
 
 ### Search & Code Intelligence (ContextStream-first)
 
-\u26A0\uFE0F **STOP: Before using Search/Glob/Grep/Read/Explore** \u2192 Call \`search(mode="auto")\` FIRST. Use local tools ONLY if ContextStream returns 0 results.
+\u26A0\uFE0F **STOP: Before using Search/Glob/Grep/Read/Explore** \u2192 Call \`search(mode="auto")\` FIRST. For stale/not-indexed projects, wait ~20s for background refresh and retry search before local fallback.
 
 **\u274C WRONG workflow (wastes tokens, slow):**
 \`\`\`
@@ -767,7 +767,7 @@ search(mode="auto", query="function implementation") \u2192 done (results includ
 2. \`search(mode="auto", query="...", limit=3)\` or \`search(mode="keyword", query="<filename>", limit=3)\`
 3. \`project(action="files")\` - file tree/list (only when needed)
 4. \`graph(action="dependencies", ...)\` - code structure
-5. Local repo scans (rg/ls/find) - ONLY if ContextStream returns no results, errors, or the user explicitly asks
+5. Local repo scans (rg/ls/find) - ONLY after refresh grace window/retry still yields no results/errors, or the user explicitly asks
 
 **Search Mode Selection:**
 
@@ -798,7 +798,7 @@ search(mode="auto", query="function implementation") \u2192 done (results includ
 
 **Search defaults:** \`search\` returns the top 3 results with compact snippets. Use \`limit\` + \`offset\` for pagination, and \`content_max_chars\` to expand snippets when needed.
 
-If ContextStream returns results, stop and use them. NEVER use local Search/Explore/Read unless you need exact code edits or ContextStream returned 0 results.
+If ContextStream returns results, stop and use them. NEVER use local Search/Explore/Read unless you need exact code edits, or refresh grace window + retry still returns 0 results.
 
 **Code Analysis:**
 - Dependencies: \`graph(action="dependencies", file_path="...")\`
@@ -927,7 +927,7 @@ var CONTEXTSTREAM_RULES_MINIMAL = `
 3. Narrow bypass: immediate read-only ContextStream calls are allowed only when prior context is fresh and no state-changing tool has run
 
 **BEFORE Glob/Grep/Read/Search/Explore/Task/EnterPlanMode:**
-\u2192 \`search(mode="auto", query="...")\` FIRST \u2014 local tools ONLY if 0 results
+\u2192 \`search(mode="auto", query="...")\` FIRST \u2014 for stale/not-indexed, wait ~20s for refresh then retry before local fallback
 
 **HOOKS: \`<system-reminder>\` tags contain instructions \u2014 FOLLOW THEM**
 </contextstream_protocol>
@@ -1150,10 +1150,10 @@ search(mode="auto", query="what you're looking for")
 \u2192 Use this instead of Explore/Task/EnterPlanMode for file discovery.
 
 **IF project is NOT indexed or very stale (>7 days):**
-\u2192 Use local tools (Glob/Grep/Read) directly
+\u2192 Wait up to ~20s for background refresh, retry \`search(mode="auto", ...)\`, then allow local tools only after the grace window
 \u2192 OR run \`project(action="index")\` first, then search
 
-**IF ContextStream search returns 0 results or errors:**
+**IF ContextStream search still returns 0 results or errors after retry/window:**
 \u2192 Use local tools (Glob/Grep/Read) as fallback
 
 ### Choose Search Mode Intelligently:
@@ -1179,9 +1179,8 @@ search(mode="auto", query="what you're looking for")
 - Then use local Read/Grep only on paths returned by ContextStream.
 
 ### When Local Tools Are OK:
-\u2705 Project is not indexed
-\u2705 Index is stale/outdated (>7 days old)
-\u2705 ContextStream search returns 0 results
+\u2705 Stale/not-indexed grace window has elapsed (~20s default, configurable)
+\u2705 ContextStream search still returns 0 results after retry
 \u2705 ContextStream returns errors
 \u2705 User explicitly requests local tools
 
@@ -1276,7 +1275,7 @@ var ANTIGRAVITY_SUPPLEMENT = `
   2. Project is indexed and \`search(mode="auto", ...)\` is retried before local fallbacks
   3. Instructions file contains the current ContextStream managed block
 `;
-var NO_HOOKS_EDITORS = ["copilot", "codex", "opencode", "aider", "antigravity"];
+var NO_HOOKS_EDITORS = ["copilot", "codex", "opencode", "aider", "antigravity", "kilo"];
 var TEMPLATES = {
   codex: {
     filename: "AGENTS.md",
@@ -1318,7 +1317,7 @@ ${rules}
 `
   },
   kilo: {
-    filename: ".kilocode/rules/contextstream.md",
+    filename: ".kilo/rules/contextstream.md",
     description: "Kilo Code AI rules",
     build: (rules) => `# Kilo Code Rules
 ${rules}
@@ -1476,6 +1475,8 @@ function getOrCreateEntry(state, cwd) {
     require_init: false,
     last_context_at: void 0,
     last_state_change_at: void 0,
+    index_wait_started_at: void 0,
+    index_wait_until: void 0,
     updated_at: nowIso()
   };
   state.workspaces[cwd] = created;

package/dist/hooks/user-prompt-submit.js

@@ -235,6 +235,8 @@ function getOrCreateEntry(state, cwd) {
     require_init: false,
     last_context_at: void 0,
     last_state_change_at: void 0,
+    index_wait_started_at: void 0,
+    index_wait_until: void 0,
     updated_at: nowIso()
   };
   state.workspaces[cwd] = created;
@@ -298,13 +300,12 @@ var FULL_REMINDER = `[CONTEXTSTREAM RULES - MANDATORY]
 2. FOR CODE SEARCH: Check index status, then search appropriately
    \u26A0\uFE0F BEFORE searching: mcp__contextstream__project(action="index_status")
    \u2705 IF indexed & fresh: Use mcp__contextstream__search(mode="auto", query="...") BEFORE Glob/Grep/Read/Explore/Task/EnterPlanMode
-   \u2705 IF NOT indexed OR stale: Use local tools (Glob/Grep/Read) directly
-   \u2705 IF search returns 0 results: Fallback to local tools (Glob/Grep/Read)
+   \u2705 IF NOT indexed OR stale: wait for background refresh up to ~20s, retry mcp__contextstream__search(mode="auto", query="..."), then allow local tools only after the grace window
+   \u2705 IF search still returns 0 results after retry/window: fallback to local tools (Glob/Grep/Read)
 
 3. WHEN LOCAL TOOLS (Glob/Grep/Read) ARE OK:
-   \u2705 Project is NOT indexed (index_status.indexed=false)
-   \u2705 Index is stale/outdated (>7 days old)
-   \u2705 ContextStream search returns 0 results or errors
+   \u2705 Stale/not-indexed grace window has elapsed (~20s default, configurable)
+   \u2705 ContextStream search still returns 0 results or errors after retry
    \u2705 User explicitly requests local tools
 
 4. FOR PLANS & TASKS: Use ContextStream, not file-based plans
@@ -727,23 +728,22 @@ Returns: \`indexed\` (true/false), \`last_indexed_at\`, \`file_count\`
 \u2192 Use \`search(mode="auto", query="...")\`
 
 **IF indexed=false OR last_indexed_at is stale (>7 days):**
-\u2192 Use local tools (Glob/Grep/Read) directly
-\u2192 OR run \`project(action="index")\` first, then search
+\u2192 Wait up to ~20s for background refresh, retry \`search(mode="auto", query="...")\`
+\u2192 After grace window: local tools are allowed if search still misses
 
-**IF search returns 0 results or errors:**
+**IF search still returns 0 results or errors after retry/window:**
 \u2192 Fallback to local tools (Glob/Grep/Read)
 
 ### \u2705 When Local Tools (Glob/Grep/Read) Are OK:
-- Project is NOT indexed
-- Index is stale/outdated (>7 days)
-- ContextStream search returns 0 results
+- Stale/not-indexed grace window has elapsed (~20s default, configurable)
+- ContextStream search still returns 0 results after retry
 - ContextStream returns errors
 - User explicitly requests local tools
 
 ### On Session Start:
 1. Call \`init(folder_path="...")\` - triggers initial indexing
 2. Check \`project(action="index_status")\` before searching
-3. If not indexed: use local tools OR wait for indexing
+3. If not indexed: wait for background refresh (~20s), retry search, then use local tools only after the grace window
 
 ### After File Changes (Edit/Write/Create):
 Files are NOT auto-indexed. You MUST: