@comfanion/usethis_search 4.1.0-dev.3 → 4.2.0-dev.1

package/hooks/message-before.ts

@@ -1,27 +1,29 @@
 /**
  * Workspace Context Injection Hook
  *
- * Uses "experimental.chat.messages.transform" to inject workspace files
- * into the conversation context. The AI sees attached files as part of
+ * Uses "experimental.chat.messages.transform" to inject workspace chunks
+ * into the conversation context. The AI sees attached chunks as part of
  * the message stream — no read() needed.
  *
  * Architecture:
- *   search("auth") → workspaceCache.attach(files)
- *   [this hook]    → inject cached files into messages
- *   AI sees:       full file content in context
- *   Chat history:  search outputs auto-pruned (files already in workspace)
+ *   search("auth") → workspaceCache.attach(chunks)
+ *   [this hook]    → inject cached chunks into messages (grouped by file)
+ *   AI sees:       chunk content organized by file
+ *   Chat history:  search outputs auto-pruned (chunks already in workspace)
  *
  * Two responsibilities:
  *   1. INJECT: synthetic <workspace_context> message before last user message
  *   2. PRUNE:  replace old search tool outputs with compact summaries
- *      (the full content is already in workspace injection — no need to keep
+ *      (the chunk content is already in workspace injection — no need to keep
  *       the big search output in chat history)
  *
  * Injection strategy:
  *   - Injects a synthetic user message with <workspace_context> BEFORE
- *     the last user message (so AI sees files as "already known" context)
+ *     the last user message (so AI sees chunks as "already known" context)
  *   - Uses cache_control: ephemeral for Anthropic prompt caching (90% savings)
- *   - Groups files: search-main first, then search-graph, then manual
+ *   - Groups chunks by file: search-main first, then search-graph, then manual
+ *   - Within each file: chunks sorted by chunkIndex (order in file)
+ *   - Shows chunk metadata: function name, heading, line numbers
  */
 
 import type { SessionState } from "./types.ts"
@@ -77,41 +79,51 @@ export function createWorkspaceInjectionHandler(state: SessionState) {
       if (entries.length === 0) return
     }
 
-    // ── Build workspace context block ─────────────────────────────────────
-    const totalTokens = workspaceCache.totalTokens
-    const fileCount = workspaceCache.size
+     // ── Build workspace context block ─────────────────────────────────────
+     const totalTokens = workspaceCache.totalTokens
+     const chunkCount = entries.length
 
-    let workspace = `<workspace_context files="${fileCount}" tokens="${totalTokens}">\n`
+     // Group chunks by file path
+     const byFile = new Map<string, typeof entries>()
+     for (const entry of entries) {
+       if (!byFile.has(entry.path)) {
+         byFile.set(entry.path, [])
+       }
+       byFile.get(entry.path)!.push(entry)
+     }
 
-    // Group by role for clear structure
-    const mainFiles = entries.filter(e => e.role === "search-main")
-    const graphFiles = entries.filter(e => e.role === "search-graph")
-    const manualFiles = entries.filter(e => e.role === "manual")
+     // Sort chunks within each file by chunkIndex
+     for (const chunks of byFile.values()) {
+       chunks.sort((a, b) => a.chunkIndex - b.chunkIndex)
+     }
 
-    // Main search results
-    if (mainFiles.length > 0) {
-      for (const entry of mainFiles) {
-        workspace += formatFileEntry(entry)
-      }
-    }
+     const fileCount = byFile.size
 
-    // Graph relations (imports, extends, used_by)
-    if (graphFiles.length > 0) {
-      workspace += `\n<!-- Graph relations -->\n`
-      for (const entry of graphFiles) {
-        workspace += formatFileEntry(entry)
-      }
-    }
+     let workspace = `<workspace_context chunks="${chunkCount}" files="${fileCount}" tokens="${totalTokens}">\n`
 
-    // Manually attached files
-    if (manualFiles.length > 0) {
-      workspace += `\n<!-- Manually attached -->\n`
-      for (const entry of manualFiles) {
-        workspace += formatFileEntry(entry)
-      }
-    }
+     // Group by role for clear structure
+     const mainFiles = entries.filter(e => e.role === "search-main")
+     const graphFiles = entries.filter(e => e.role === "search-graph")
+     const manualFiles = entries.filter(e => e.role === "manual")
+
+     // Main search results
+     if (mainFiles.length > 0) {
+       workspace += formatChunksByFile(mainFiles, byFile)
+     }
 
-    workspace += `</workspace_context>`
+     // Graph relations (imports, extends, used_by)
+     if (graphFiles.length > 0) {
+       workspace += `\n<!-- Search graph relations -->\n`
+       workspace += formatChunksByFile(graphFiles, byFile)
+     }
+
+     // Manually attached chunks
+     if (manualFiles.length > 0) {
+       workspace += `\n<!-- Manually attached -->\n`
+       workspace += formatChunksByFile(manualFiles, byFile)
+     }
+
+     workspace += `</workspace_context>`
 
     // ── Inject into messages ──────────────────────────────────────────────
     // Find the last real user message and inject workspace BEFORE it
@@ -146,17 +158,71 @@ export function createWorkspaceInjectionHandler(state: SessionState) {
 
 // ── Helpers ─────────────────────────────────────────────────────────────────
 
-function formatFileEntry(entry: ReturnType<typeof workspaceCache.getAll>[0]): string {
-  let block = `\n## ${entry.path}\n`
+/**
+ * Format chunks grouped by file path.
+ * Groups chunks from the same file together, sorted by chunkIndex.
+ */
+function formatChunksByFile(
+  entries: ReturnType<typeof workspaceCache.getAll>,
+  byFile: Map<string, ReturnType<typeof workspaceCache.getAll>>
+): string {
+  let output = ""
+  const processedFiles = new Set<string>()
+
+  for (const entry of entries) {
+    // Skip if we already processed this file
+    if (processedFiles.has(entry.path)) continue
+    processedFiles.add(entry.path)
+
+    const chunks = byFile.get(entry.path) || []
+    output += formatFileWithChunks(entry.path, chunks)
+  }
+
+  return output
+}
 
-  // Metadata line
+/**
+ * Format a single file with all its chunks.
+ */
+function formatFileWithChunks(
+  filePath: string,
+  chunks: ReturnType<typeof workspaceCache.getAll>
+): string {
+  let block = `\n## ${filePath}\n`
+
+  // Chunk list comment: "Chunks: 2, 5 (partial file)"
+  const chunkIndices = chunks.map(c => c.chunkIndex).join(", ")
+  const isPartial = chunks.length > 0 ? " (partial file)" : ""
+  block += `<!-- Chunks: ${chunkIndices}${isPartial} -->\n`
+
+  // Format each chunk
+  for (const chunk of chunks) {
+    block += formatChunk(chunk)
+  }
+
+  return block
+}
+
+/**
+ * Format a single chunk with metadata.
+ */
+function formatChunk(entry: ReturnType<typeof workspaceCache.getAll>[0]): string {
+  let block = ""
+
+  // Chunk subheader: "### Chunk N: description"
+  const description = entry.metadata?.function_name || entry.metadata?.heading_context || "code"
+  block += `\n### Chunk ${entry.chunkIndex}: ${description}\n`
+
+  // Chunk metadata line
   const meta: string[] = []
   if (entry.score !== undefined) meta.push(`score: ${entry.score.toFixed(3)}`)
   if (entry.metadata?.language) meta.push(entry.metadata.language)
-  if (entry.metadata?.function_name) meta.push(`fn: ${entry.metadata.function_name}`)
   if (entry.metadata?.class_name) meta.push(`class: ${entry.metadata.class_name}`)
+  if (entry.metadata?.startLine !== undefined && entry.metadata?.endLine !== undefined) {
+    meta.push(`lines: ${entry.metadata.startLine}-${entry.metadata.endLine}`)
+  }
   if (entry.metadata?.relation) {
-    const mainBase = entry.metadata.mainFile?.split("/").pop() || "?"
+    const mainBase = entry.metadata.mainChunkId?.split(":").pop() || "?"
     meta.push(`${entry.metadata.relation} from ${mainBase}`)
   }
 
@@ -164,7 +230,7 @@ function formatFileEntry(entry: ReturnType<typeof workspaceCache.getAll>[0]): st
     block += `<!-- ${meta.join(" | ")} -->\n`
   }
 
-  // File content
+  // Chunk content
   const lang = entry.metadata?.language || ""
   block += `\`\`\`${lang}\n`
   block += entry.content

package/hooks/tool-substitution.ts

@@ -53,8 +53,12 @@ export function createToolSubstitutionHandler(state: SessionState, cache?: Works
     // Mark files as dirty so read() substitution is bypassed until freshen()
     if (input.tool === "edit" || input.tool === "write" || input.tool === "Edit" || input.tool === "Write") {
       const filePath = output.metadata?.filePath || output.metadata?.path || extractFilePathFromTitle(output.title)
-      if (filePath && wsCache.has(filePath)) {
-        wsCache.markDirty(filePath)
+      if (filePath) {
+        // Mark dirty if file has any chunks in workspace
+        const chunks = wsCache.getChunksByPath(filePath)
+        if (chunks.length > 0) {
+          wsCache.markDirty(filePath)
+        }
       }
       return // edit/write don't need output substitution
     }
@@ -80,13 +84,13 @@ export function createToolSubstitutionHandler(state: SessionState, cache?: Works
 }
 
 /**
- * Substitute read() output if file is in workspace.
+ * Substitute read() output if file has chunks in workspace.
  *
  * Input: { filePath: "src/auth.ts", offset?: 0, limit?: 100 }
  * Output: "export function login(...)\n..."
  *
- * If file in workspace AND no offset/limit (full read):
- *   Replace with: "[File "src/auth.ts" is in workspace context — see <workspace_context> for full content.]"
+ * If file has chunks in workspace AND no offset/limit (full read):
+ *   Replace with: "[File "src/auth.ts" has N chunks in workspace (chunks: 2, 5, 7) — see <workspace_context>]"
  *
  * If offset/limit present (partial read):
  *   Keep original (partial reads are not in workspace injection)
@@ -101,14 +105,18 @@ function substituteReadOutput(output: { title: string; output: string; metadata:
     const isPartialRead = output.metadata?.offset !== undefined || output.metadata?.limit !== undefined
     if (isPartialRead) return
 
-    // Check if file is in workspace
-    if (!cache.has(filePath)) return
-
     // Don't substitute if file was modified (dirty) — workspace has stale content
     if (cache.isDirty(filePath)) return
 
-    // Replace output with compact message
-    output.output = `[File "${filePath}" is in workspace context — see <workspace_context> for full content.]`
+    // Check if file has chunks in workspace
+    const chunks = cache.getChunksByPath(filePath)
+    if (chunks.length === 0) return
+
+    // Build chunk ID list for message
+    const chunkIds = chunks.map(c => c.chunkIndex).join(", ")
+
+    // Replace output with compact message showing which chunks are available
+    output.output = `[File "${filePath}" has ${chunks.length} chunks in workspace (chunks: ${chunkIds}) — see <workspace_context>]`
   } catch {
     // Silently fail — don't break tool execution
   }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@comfanion/usethis_search",
-  "version": "4.1.0-dev.3",
-  "description": "OpenCode plugin: semantic search with workspace injection + tool output substitution (v4.1-dev: read() substitution, dirty file tracking)",
+  "version": "4.2.0-dev.1",
+  "description": "OpenCode plugin: semantic search with chunk-based workspace injection (v4.2-dev: chunk-level context, granular detach, improved token efficiency)",
   "type": "module",
   "main": "./index.ts",
   "exports": {

package/tools/search.ts

@@ -1,10 +1,10 @@
 /**
- * Semantic Code Search Tool (v4 — workspace injection)
+ * Semantic Code Search Tool (v5 — chunk-based workspace injection)
  *
  * Uses local embeddings + LanceDB vector store via bundled vectorizer.
- * v4: Top results + graph relations attached to workspace with full content.
+ * v5: Top N chunks + graph relations attached to workspace (chunk content only).
  *     Rest returned as summary only.
- *     AI sees full files via message.before injection — no read() needed.
+ *     AI sees chunks via message.before injection — no read() needed.
  *
  * Index data is stored in `.opencode/vectors/<index>/`.
  */
@@ -245,109 +245,89 @@ Examples:
       }
       allResults.sort((a: any, b: any) => (b._finalScore ?? 0) - (a._finalScore ?? 0))
 
-      // ── Group by file — best chunk per file, with chunk count ─────────────
-      const fileGroups = new Map<string, { best: any, chunks: any[] }>()
-      for (const r of allResults) {
-        const key = r.file
-        if (!fileGroups.has(key)) {
-          fileGroups.set(key, { best: r, chunks: [r] })
-        } else {
-          const group = fileGroups.get(key)!
-          group.chunks.push(r)
-          if ((r._finalScore ?? 0) > (group.best._finalScore ?? 0)) {
-            group.best = r
-          }
-        }
-      }
-
-      const sortedGroups = [...fileGroups.values()]
-        .sort((a, b) => (b.best._finalScore ?? 0) - (a.best._finalScore ?? 0))
-        .slice(0, limit)
-
-      if (sortedGroups.length === 0) {
-        const scope = args.searchAll ? "any index" : `index "${indexName}"`
-        const filterNote = args.filter ? ` with filter "${args.filter}"` : ""
-        return `No results found in ${scope}${filterNote} for: "${args.query}" (min score: ${minScore})\n\nTry:\n- Different keywords or phrasing\n- Remove or broaden the filter\n- search({ query: "...", searchAll: true })`
-      }
-
-      // ══════════════════════════════════════════════════════════════════════
-      // WORKSPACE ATTACH: Top N main files + graph relations (FULL CONTENT)
-      // ══════════════════════════════════════════════════════════════════════
-
-      const topGroups = sortedGroups.slice(0, wsConfig.attachTopN)
-      const restGroups = sortedGroups.slice(wsConfig.attachTopN)
-
-      const attachedMain: string[] = []
-      const attachedGraph: string[] = []
-      const alreadyAttached = new Set<string>()
-
-      for (const { best: r } of topGroups) {
-        // Skip if score too low
-        if ((r._finalScore ?? 0) < wsConfig.minScoreMain) continue
-
-        // Read full file and attach
-        try {
-          const fullPath = path.join(projectRoot, r.file)
-          const content = await fs.readFile(fullPath, "utf-8")
-
-          workspaceCache.attach({
-            path: r.file,
-            content,
-            role: "search-main",
-            attachedAt: Date.now(),
-            attachedBy: args.query,
-            score: r._finalScore,
-            metadata: {
-              language: r.language,
-              function_name: r.function_name,
-              class_name: r.class_name,
-              heading_context: r.heading_context,
-            },
-          })
-
-          attachedMain.push(r.file)
-          alreadyAttached.add(r.file)
-        } catch {
-          // File read failed — skip
-          continue
-        }
-
-        // Attach graph relations (imports, extends, used_by)
-        if (r.relatedContext && r.relatedContext.length > 0) {
-          const topRelated = r.relatedContext
-            .filter((rel: any) => rel.score >= wsConfig.minScoreRelated)
-            .sort((a: any, b: any) => b.score - a.score)
-            .slice(0, wsConfig.attachRelatedPerFile)
-
-          for (const rel of topRelated) {
-            if (alreadyAttached.has(rel.file)) continue
-
-            try {
-              const relFullPath = path.join(projectRoot, rel.file)
-              const relContent = await fs.readFile(relFullPath, "utf-8")
-
-              workspaceCache.attach({
-                path: rel.file,
-                content: relContent,
-                role: "search-graph",
-                attachedAt: Date.now(),
-                attachedBy: `${args.query} (${rel.relation} from ${r.file})`,
-                score: rel.score,
-                metadata: {
-                  language: rel.language,
-                  relation: rel.relation,
-                  mainFile: r.file,
-                },
-              })
-
-              attachedGraph.push(rel.file)
-              alreadyAttached.add(rel.file)
-            } catch {
-              // Related file read failed — skip
-            }
-          }
-        }
-      }
+       // ── Sort by final score (chunks, not files) ──────────────────────────
+       const topChunks = allResults.slice(0, limit)
+
+       if (topChunks.length === 0) {
+         const scope = args.searchAll ? "any index" : `index "${indexName}"`
+         const filterNote = args.filter ? ` with filter "${args.filter}"` : ""
+         return `No results found in ${scope}${filterNote} for: "${args.query}" (min score: ${minScore})\n\nTry:\n- Different keywords or phrasing\n- Remove or broaden the filter\n- search({ query: "...", searchAll: true })`
+       }
+
+       // ══════════════════════════════════════════════════════════════════════
+       // WORKSPACE ATTACH: Top N chunks + graph relations (CHUNK CONTENT ONLY)
+       // ══════════════════════════════════════════════════════════════════════
+
+       const mainChunks = topChunks.slice(0, wsConfig.attachTopN)
+       const restChunks = topChunks.slice(wsConfig.attachTopN)
+
+       const attachedMain: Array<{ chunkId: string; path: string }> = []
+       const attachedGraph: Array<{ chunkId: string; path: string }> = []
+       const alreadyAttached = new Set<string>()
+
+       for (const chunk of mainChunks) {
+         // Skip if score too low
+         if ((chunk._finalScore ?? 0) < wsConfig.minScoreMain) continue
+
+         // Attach chunk directly (no file read needed — chunk.content already has it)
+         const chunkId = chunk.chunkId || `${chunk.file}:chunk-${chunk.index ?? 0}`
+         
+         workspaceCache.attach({
+           chunkId,
+           path: chunk.file,
+           content: chunk.content,
+           chunkIndex: chunk.index ?? 0,
+           role: "search-main",
+           attachedAt: Date.now(),
+           attachedBy: args.query,
+           score: chunk._finalScore,
+           metadata: {
+             language: chunk.language,
+             function_name: chunk.function_name,
+             class_name: chunk.class_name,
+             heading_context: chunk.heading_context,
+             startLine: chunk.startLine,
+             endLine: chunk.endLine,
+           },
+         })
+
+         attachedMain.push({ chunkId, path: chunk.file })
+         alreadyAttached.add(chunkId)
+
+         // Attach graph relations (imports, extends, used_by)
+         if (chunk.relatedContext && chunk.relatedContext.length > 0) {
+           const topRelated = chunk.relatedContext
+             .filter((rel: any) => rel.score >= wsConfig.minScoreRelated)
+             .sort((a: any, b: any) => b.score - a.score)
+             .slice(0, wsConfig.attachRelatedPerChunk)
+
+           for (const rel of topRelated) {
+             const relChunkId = rel.chunkId || `${rel.file}:chunk-${rel.index ?? 0}`
+             if (alreadyAttached.has(relChunkId)) continue
+
+             workspaceCache.attach({
+               chunkId: relChunkId,
+               path: rel.file,
+               content: rel.content,
+               chunkIndex: rel.index ?? 0,
+               role: "search-graph",
+               attachedAt: Date.now(),
+               attachedBy: `${args.query} (${rel.relation} from ${chunkId})`,
+               score: rel.score,
+               metadata: {
+                 language: rel.language,
+                 relation: rel.relation,
+                 mainChunkId: chunkId,
+                 startLine: rel.startLine,
+                 endLine: rel.endLine,
+               },
+             })
+
+             attachedGraph.push({ chunkId: relChunkId, path: rel.file })
+             alreadyAttached.add(relChunkId)
+           }
+         }
+       }
 
       // ── Flush workspace to disk immediately (don't rely on debounce) ─────
       if (attachedMain.length > 0 || attachedGraph.length > 0) {
@@ -358,7 +338,7 @@ Examples:
       // BUILD OUTPUT: Attached (summary) + Rest (summary only)
       // ══════════════════════════════════════════════════════════════════════
 
-      const topScore = sortedGroups[0].best._finalScore ?? 0
+       const topScore = topChunks[0]?._finalScore ?? 0
       const hasBM25Only = allResults.some((r: any) => r._bm25Only)
       const scope = args.searchAll ? "all indexes" : `index "${indexName}"`
       const filterLabel = args.filter ? ` filter:"${args.filter}"` : ""
@@ -372,67 +352,65 @@ Examples:
         output += `> **Low confidence.** Best score: ${topScore.toFixed(3)}. Try more specific keywords.\n\n`
       }
 
-      // ── Attached files (summary — full content in workspace injection) ─────
-      if (attachedMain.length > 0) {
-        const totalAttached = attachedMain.length + attachedGraph.length
-        output += `### Attached to workspace (${totalAttached} files)\n\n`
-
-        for (let i = 0; i < attachedMain.length; i++) {
-          const group = topGroups.find(g => g.best.file === attachedMain[i])
-          if (!group) continue
-          const r = group.best
-          const score = (r._finalScore ?? 0).toFixed(3)
-          const chunkNote = group.chunks.length > 1 ? ` (${group.chunks.length} sections)` : ""
-
-          const metaParts: string[] = []
-          if (r.language && r.language !== "unknown") metaParts.push(r.language)
-          if (r.function_name) metaParts.push(`fn: ${r.function_name}`)
-          if (r.class_name) metaParts.push(`class: ${r.class_name}`)
-          const metaLine = metaParts.length > 0 ? ` — ${metaParts.join(", ")}` : ""
-
-          output += `${i + 1}. **${r.file}** score: ${score}${chunkNote}${metaLine}\n`
-        }
-
-        if (attachedGraph.length > 0) {
-          output += `\n**Graph relations:**\n`
-          for (const graphFile of attachedGraph) {
-            const entry = workspaceCache.get(graphFile)
-            const relation = entry?.metadata?.relation || "related"
-            const mainFile = entry?.metadata?.mainFile
-            const mainBasename = mainFile ? path.basename(mainFile) : "?"
-            output += `- ${graphFile} (${relation} from ${mainBasename})\n`
-          }
-        }
-        output += `\n`
-      }
-
-      // ── Rest files (summary only — not attached) ──────────────────────────
-      if (restGroups.length > 0) {
-        output += `### Additional results (summary only)\n\n`
-        for (let i = 0; i < restGroups.length; i++) {
-          const { best: r, chunks } = restGroups[i]
-          const score = (r._finalScore ?? 0).toFixed(3)
-          const chunkNote = chunks.length > 1 ? ` (${chunks.length} sections)` : ""
-          const indexLabel = args.searchAll ? ` [${r._index}]` : ""
-
-          const metaParts: string[] = []
-          if (r.language && r.language !== "unknown") metaParts.push(r.language)
-          if (r.function_name) metaParts.push(`fn: ${r.function_name}`)
-          if (r.class_name) metaParts.push(`class: ${r.class_name}`)
-          const metaLine = metaParts.length > 0 ? ` — ${metaParts.join(", ")}` : ""
-
-          output += `${attachedMain.length + i + 1}. ${r.file}${indexLabel} score: ${score}${chunkNote}${metaLine}\n`
-        }
-        output += `\nUse \`workspace.attach("path")\` to attach additional files.\n`
-      }
-
-      // ── Footer ────────────────────────────────────────────────────────────
-      const totalChunks = allResults.length
-      const uniqueFiles = sortedGroups.length
-      output += `\n---\n`
-      output += `*${uniqueFiles} files (${totalChunks} chunks) | `
-      output += `Workspace: ${workspaceCache.size} files, ${workspaceCache.totalTokens.toLocaleString()} tokens*\n`
-      output += `*Attached files are in workspace context — reference them directly without read().*`
+       // ── Attached chunks (summary — full content in workspace injection) ─────
+       if (attachedMain.length > 0) {
+         const totalAttached = attachedMain.length + attachedGraph.length
+         output += `### Attached to workspace (${totalAttached} chunks)\n\n`
+
+         for (let i = 0; i < attachedMain.length; i++) {
+           const { chunkId, path: filePath } = attachedMain[i]
+           const chunk = mainChunks[i]
+           if (!chunk) continue
+           
+           const score = (chunk._finalScore ?? 0).toFixed(3)
+           const metaParts: string[] = []
+           if (chunk.language && chunk.language !== "unknown") metaParts.push(chunk.language)
+           if (chunk.function_name) metaParts.push(`fn: ${chunk.function_name}`)
+           if (chunk.class_name) metaParts.push(`class: ${chunk.class_name}`)
+           const metaLine = metaParts.length > 0 ? ` — ${metaParts.join(", ")}` : ""
+
+           output += `${i + 1}. **${chunkId}** (${filePath}) score: ${score}${metaLine}\n`
+         }
+
+         if (attachedGraph.length > 0) {
+           output += `\n**Graph relations:**\n`
+           for (const { chunkId, path: filePath } of attachedGraph) {
+             const entry = workspaceCache.get(chunkId)
+             const relation = entry?.metadata?.relation || "related"
+             const mainChunkId = entry?.metadata?.mainChunkId
+             const mainBasename = mainChunkId ? mainChunkId.split(":")[0] : "?"
+             output += `- ${chunkId} (${relation} from ${mainBasename})\n`
+           }
+         }
+         output += `\n`
+       }
+
+       // ── Rest chunks (summary only — not attached) ──────────────────────────
+       if (restChunks.length > 0) {
+         output += `### Additional results (summary only)\n\n`
+         for (let i = 0; i < restChunks.length; i++) {
+           const chunk = restChunks[i]
+           const chunkId = chunk.chunkId || `${chunk.file}:chunk-${chunk.index ?? 0}`
+           const score = (chunk._finalScore ?? 0).toFixed(3)
+           const indexLabel = args.searchAll ? ` [${chunk._index}]` : ""
+
+           const metaParts: string[] = []
+           if (chunk.language && chunk.language !== "unknown") metaParts.push(chunk.language)
+           if (chunk.function_name) metaParts.push(`fn: ${chunk.function_name}`)
+           if (chunk.class_name) metaParts.push(`class: ${chunk.class_name}`)
+           const metaLine = metaParts.length > 0 ? ` — ${metaParts.join(", ")}` : ""
+
+           output += `${attachedMain.length + i + 1}. ${chunkId}${indexLabel} score: ${score}${metaLine}\n`
+         }
+         output += `\nUse \`workspace.attach(chunkId)\` to attach additional chunks.\n`
+       }
+
+       // ── Footer ────────────────────────────────────────────────────────────
+       const totalChunks = allResults.length
+       output += `\n---\n`
+       output += `*${totalChunks} chunks found | `
+       output += `Workspace: ${workspaceCache.size} chunks, ${workspaceCache.totalTokens.toLocaleString()} tokens*\n`
+       output += `*Attached chunks are in workspace context — reference them directly without read().*`
 
       return output
     } catch (error: any) {