@comfanion/usethis_search 3.0.1 → 4.1.0-dev.1

package/hooks/message-before.ts

@@ -0,0 +1,261 @@
+/**
+ * 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
+ * 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)
+ *
+ * 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 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)
+ *   - Uses cache_control: ephemeral for Anthropic prompt caching (90% savings)
+ *   - Groups files: search-main first, then search-graph, then manual
+ */
+
+import type { SessionState } from "./types.ts"
+import { workspaceCache } from "../cache/manager.ts"
+
+// ── Types matching OpenCode plugin message format ───────────────────────────
+
+interface MessagePart {
+  type: string
+  content?: string
+  text?: string
+  [key: string]: any
+}
+
+interface Message {
+  info: {
+    role: "user" | "assistant" | "tool"
+    [key: string]: any
+  }
+  parts: MessagePart[]
+  [key: string]: any
+}
+
+// ── Hook ────────────────────────────────────────────────────────────────────
+
+/**
+ * Create the messages transform handler that injects workspace context.
+ */
+export function createWorkspaceInjectionHandler(state: SessionState) {
+  return async (_input: {}, output: { messages: Message[] }) => {
+    // Don't inject or prune for sub-agents (title generation, etc.)
+    if (state.isSubAgent) return
+
+    // ── Prune: replace old search tool outputs with compact summaries ────
+    // Files are already in workspace injection — no need for big search
+    // output in chat history. This runs even when workspace is empty
+    // (handles case where workspace was cleared but old search outputs remain).
+    const wsConfig = workspaceCache.getConfig()
+    if (wsConfig.autoPruneSearch !== false) {
+      pruneSearchToolOutputs(output.messages)
+    }
+
+    let entries = workspaceCache.getAll()
+
+    // Nothing in workspace — skip injection (but pruning already happened)
+    if (entries.length === 0) return
+
+    // ── Freshen: re-read changed files from disk ──────────────────────────
+    const { updated, removed } = await workspaceCache.freshen()
+    if (updated > 0 || removed > 0) {
+      // Re-fetch entries after freshen (some may be removed)
+      entries = workspaceCache.getAll()
+      if (entries.length === 0) return
+    }
+
+    // ── Build workspace context block ─────────────────────────────────────
+    const totalTokens = workspaceCache.totalTokens
+    const fileCount = workspaceCache.size
+
+    let workspace = `<workspace_context files="${fileCount}" tokens="${totalTokens}">\n`
+
+    // 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) {
+      for (const entry of mainFiles) {
+        workspace += formatFileEntry(entry)
+      }
+    }
+
+    // Graph relations (imports, extends, used_by)
+    if (graphFiles.length > 0) {
+      workspace += `\n<!-- Graph relations -->\n`
+      for (const entry of graphFiles) {
+        workspace += formatFileEntry(entry)
+      }
+    }
+
+    // Manually attached files
+    if (manualFiles.length > 0) {
+      workspace += `\n<!-- Manually attached -->\n`
+      for (const entry of manualFiles) {
+        workspace += formatFileEntry(entry)
+      }
+    }
+
+    workspace += `</workspace_context>`
+
+    // ── Inject into messages ──────────────────────────────────────────────
+    // Find the last real user message and inject workspace BEFORE it
+    // This way AI sees files as "already available context"
+
+    const lastUserIdx = findLastUserMessageIndex(output.messages)
+    if (lastUserIdx === -1) return
+
+    // Create synthetic workspace message (inserted before last user message)
+    const workspaceMessage: Message = {
+      info: {
+        role: "user",
+        // Mark as synthetic so DCP doesn't prune it
+        _synthetic: true,
+        _workspace_injection: true,
+      },
+      parts: [
+        {
+          type: "text",
+          content: workspace,
+          // Anthropic prompt caching — content that doesn't change
+          // between turns gets cached at 90% discount
+          cache_control: { type: "ephemeral" },
+        },
+      ],
+    }
+
+    // Insert before last user message
+    output.messages.splice(lastUserIdx, 0, workspaceMessage)
+  }
+}
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function formatFileEntry(entry: ReturnType<typeof workspaceCache.getAll>[0]): string {
+  let block = `\n## ${entry.path}\n`
+
+  // 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?.relation) {
+    const mainBase = entry.metadata.mainFile?.split("/").pop() || "?"
+    meta.push(`${entry.metadata.relation} from ${mainBase}`)
+  }
+
+  if (meta.length > 0) {
+    block += `<!-- ${meta.join(" | ")} -->\n`
+  }
+
+  // File content
+  const lang = entry.metadata?.language || ""
+  block += `\`\`\`${lang}\n`
+  block += entry.content
+  if (!entry.content.endsWith("\n")) block += "\n"
+  block += `\`\`\`\n`
+
+  return block
+}
+
+function findLastUserMessageIndex(messages: Message[]): number {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (messages[i]?.info?.role === "user") {
+      // Skip synthetic messages
+      if ((messages[i].info as any)._synthetic) continue
+      return i
+    }
+  }
+  return -1
+}
+
+// ── Search output pruning ────────────────────────────────────────────────────
+
+/**
+ * Minimum output length to consider pruning.
+ * Short outputs (errors, "no results") are kept as-is.
+ */
+const MIN_PRUNE_LENGTH = 500
+
+/**
+ * Marker prefix that search tool outputs start with.
+ * Used to identify search results in chat history.
+ */
+const SEARCH_OUTPUT_MARKER = '## Search: "'
+
+/**
+ * Replace search tool outputs in chat history with compact summaries.
+ *
+ * Why: search() returns a big markdown block with file listings, scores, etc.
+ * After workspace injection, the full file content is already in context.
+ * Keeping the search output wastes tokens — replace it with a 1-line summary.
+ *
+ * Only prunes completed search calls with output longer than MIN_PRUNE_LENGTH.
+ * The last search output is kept (the agent may still be referencing it).
+ */
+export function pruneSearchToolOutputs(messages: Message[]): void {
+  // Find all search tool parts (completed, with long output)
+  const searchParts: { msgIdx: number; partIdx: number; part: MessagePart }[] = []
+
+  for (let i = 0; i < messages.length; i++) {
+    const msg = messages[i]
+    const parts = Array.isArray(msg.parts) ? msg.parts : []
+
+    for (let j = 0; j < parts.length; j++) {
+      const part = parts[j]
+      if (
+        part.type === "tool" &&
+        part.tool === "search" &&
+        part.state?.status === "completed" &&
+        typeof part.state?.output === "string" &&
+        part.state.output.length > MIN_PRUNE_LENGTH &&
+        part.state.output.startsWith(SEARCH_OUTPUT_MARKER)
+      ) {
+        searchParts.push({ msgIdx: i, partIdx: j, part })
+      }
+    }
+  }
+
+  // Keep the last search output (agent may reference it) — prune the rest
+  if (searchParts.length <= 1) return
+
+  const toPrune = searchParts.slice(0, -1)
+
+  for (const { part } of toPrune) {
+    const output = part.state.output as string
+
+    // Extract query from output: ## Search: "query" (...)
+    const queryMatch = output.match(/^## Search: "([^"]+)"/)
+    const query = queryMatch?.[1] || "?"
+
+    // Extract file count from output: *N files (M chunks)...*
+    const filesMatch = output.match(/\*(\d+) files? \((\d+) chunks?\)/)
+    const fileCount = filesMatch?.[1] || "?"
+    const chunkCount = filesMatch?.[2] || "?"
+
+    // Extract attached count: ### Attached to workspace (N files)
+    const attachedMatch = output.match(/### Attached to workspace \((\d+) files?\)/)
+    const attachedCount = attachedMatch?.[1] || "0"
+
+    // Replace with compact summary
+    part.state.output =
+      `[Search "${query}" — ${fileCount} files (${chunkCount} chunks), ` +
+      `${attachedCount} attached to workspace. Full content available via workspace context.]`
+  }
+}

package/hooks/types.ts

@@ -0,0 +1,23 @@
+/**
+ * Shared types for hooks.
+ *
+ * Mirrors the minimal SessionState needed by workspace hooks.
+ * We avoid importing from DCP directly to keep usethis_search independent.
+ */
+
+export interface SessionState {
+  /** Current session ID (from "chat.message" hook) */
+  sessionId: string | null
+  /** Is this a sub-agent (title gen, summarizer, etc.)? */
+  isSubAgent: boolean
+}
+
+/**
+ * Create initial session state.
+ */
+export function createSessionState(): SessionState {
+  return {
+    sessionId: null,
+    isSubAgent: false,
+  }
+}

package/index.ts

@@ -1,10 +1,31 @@
 import type { Plugin } from "@opencode-ai/plugin"
 
 import search from "./tools/search"
+import { workspace_list, workspace_attach, workspace_detach, workspace_clear, workspace_restore } from "./tools/workspace"
 import FileIndexerPlugin from "./file-indexer"
+import { workspaceCache } from "./cache/manager"
+import { createWorkspaceInjectionHandler } from "./hooks/message-before"
+import { createToolSubstitutionHandler } from "./hooks/tool-substitution"
+import { createSessionState } from "./hooks/types"
+import { getWorkspaceConfig } from "./vectorizer/index.ts"
+
+const INTERNAL_AGENT_SIGNATURES = [
+  "You are a title generator",
+  "You are a helpful AI assistant tasked with summarizing conversations",
+  "Summarize what was done in this conversation",
+]
 
 const UsethisSearchPlugin: Plugin = async ({ directory, client }) => {
-  // Start file indexer (background indexing + event handling)
+  // ── Initialize workspace cache with project root + config from yaml ─────
+  // sessionId will be set on first "chat.message" event
+  const wsConfig = getWorkspaceConfig()
+  workspaceCache.updateConfig(wsConfig)
+  await workspaceCache.init(directory)
+
+  // ── Session state (tracks sessionId, sub-agent detection) ───────────────
+  const state = createSessionState()
+
+  // ── Start file indexer (background indexing + event handling) ────────────
   let fileIndexerEvent: ((args: any) => Promise<void>) | null = null
   try {
     const hooks = await FileIndexerPlugin({ directory, client } as any)
@@ -14,10 +35,51 @@ const UsethisSearchPlugin: Plugin = async ({ directory, client }) => {
   }
 
   return {
+    // ── Tools ───────────────────────────────────────────────────────────
     tool: {
       search,
+      workspace_list,
+      workspace_attach,
+      workspace_detach,
+      workspace_clear,
+      workspace_restore,
+    },
+
+    // ── Hooks ───────────────────────────────────────────────────────────
+
+    // Inject workspace files into message context (before LLM sees them)
+    "experimental.chat.messages.transform": createWorkspaceInjectionHandler(state),
+
+    // Substitute tool outputs when files are in workspace
+    "tool.execute.after": createToolSubstitutionHandler(state),
+
+    // Detect sub-agents (title gen, summarizer) via system prompt
+    "experimental.chat.system.transform": async (_input: unknown, output: { system: string[] }) => {
+      const systemText = output.system.join("\n")
+      if (INTERNAL_AGENT_SIGNATURES.some(sig => systemText.includes(sig))) {
+        state.isSubAgent = true
+      } else {
+        state.isSubAgent = false
+      }
+    },
+
+    // Track session ID + init workspace per-session persistence
+    "chat.message": async (input: {
+      sessionID: string
+      agent?: string
+      model?: { providerID: string; modelID: string }
+      messageID?: string
+      variant?: string
+    }) => {
+      if (input.sessionID && input.sessionID !== state.sessionId) {
+        state.sessionId = input.sessionID
+
+        // Re-init workspace with actual session ID (first time only)
+        await workspaceCache.init(directory, input.sessionID)
+      }
     },
 
+    // ── Events ──────────────────────────────────────────────────────────
     event: async (args: any) => {
       if (fileIndexerEvent) {
         try {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@comfanion/usethis_search",
-  "version": "3.0.1",
-  "description": "OpenCode plugin: semantic search with graph-based context (v3: graph relations, 1-hop context, LSP + regex analyzers)",
+  "version": "4.1.0-dev.1",
+  "description": "OpenCode plugin: semantic search with workspace injection + tool output substitution (v4.1-dev: read() substitution, dirty file tracking)",
   "type": "module",
   "main": "./index.ts",
   "exports": {
@@ -24,6 +24,10 @@
     "file-indexer.ts",
     "tools/search.ts",
     "tools/codeindex.ts",
+    "tools/workspace.ts",
+    "cache/manager.ts",
+    "hooks/message-before.ts",
+    "hooks/types.ts",
     "vectorizer/index.ts",
     "vectorizer/content-cleaner.ts",
     "vectorizer/metadata-extractor.ts",

package/tools/search.ts

@@ -1,8 +1,11 @@
 /**
- * Semantic Code Search Tool (v3)
+ * Semantic Code Search Tool (v4 — workspace injection)
  *
  * Uses local embeddings + LanceDB vector store via bundled vectorizer.
- * v3: simplified agent API — 5 params, config-driven defaults, smart filter.
+ * v4: Top results + graph relations attached to workspace with full content.
+ *     Rest returned as summary only.
+ *     AI sees full files via message.before injection — no read() needed.
+ *
  * Index data is stored in `.opencode/vectors/<index>/`.
  */
 
@@ -11,6 +14,7 @@ import path from "path"
 import fs from "fs/promises"
 
 import { CodebaseIndexer, getSearchConfig, getIndexer, releaseIndexer } from "../vectorizer/index.ts"
+import { workspaceCache } from "../cache/manager.ts"
 
 // ── Extension → language mapping (for filter parsing) ─────────────────────
 const EXT_TO_LANG: Record<string, string> = {
@@ -88,7 +92,7 @@ function parseFilter(filter: string): {
 }
 
 export default tool({
-  description: `Search the codebase semantically. Use this to find relevant code snippets, functions, or files based on meaning, not just text matching.
+  description: `Search the codebase semantically. Top results are attached to workspace with full content (visible via context injection). Rest returned as summary.
 
 Available indexes:
 - "code" (default) - Source code files (*.js, *.ts, *.py, *.go, etc.)
@@ -123,6 +127,9 @@ Examples:
       const minScore = cfg.min_score ?? 0.35
       const includeArchived = cfg.include_archived ?? false
 
+      // Workspace config
+      const wsConfig = workspaceCache.getConfig()
+
       // Parse filter into path/language constraints
       const filterParsed = args.filter ? parseFilter(args.filter) : {}
 
@@ -209,8 +216,6 @@ Examples:
         const needle = filterParsed.pathContains.toLowerCase()
         allResults = allResults.filter(r => r.file && r.file.toLowerCase().includes(needle))
       }
-      // Language filter is already passed to searchOptions above, but double-check
-      // in case vectorizer didn't filter (e.g. docs index has no language field)
       if (filterParsed.language) {
         allResults = allResults.filter(r => !r.language || r.language === filterParsed.language || r.language === "unknown")
       }
@@ -265,84 +270,170 @@ Examples:
         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 })`
       }
 
-      // ── Confidence signal ──────────────────────────────────────────────────
+      // ══════════════════════════════════════════════════════════════════════
+      // 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
+            }
+          }
+        }
+      }
+
+      // ── Flush workspace to disk immediately (don't rely on debounce) ─────
+      if (attachedMain.length > 0 || attachedGraph.length > 0) {
+        workspaceCache.save().catch(() => {})
+      }
+
+      // ══════════════════════════════════════════════════════════════════════
+      // BUILD OUTPUT: Attached (summary) + Rest (summary only)
+      // ══════════════════════════════════════════════════════════════════════
+
       const topScore = sortedGroups[0].best._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}"` : ""
-      let output = `## Search Results for: "${args.query}" (${scope}${filterLabel})\n\n`
+      let output = `## Search: "${args.query}" (${scope}${filterLabel})\n\n`
 
       if (hasBM25Only) {
-        output += `> **BM25-only mode** — vector embeddings not yet available. Results are keyword-based. Quality will improve after embedding completes.\n\n`
+        output += `> **BM25-only mode** -- vector embeddings not yet available. Quality will improve after embedding completes.\n\n`
       }
 
       if (topScore < 0.45) {
-        output += `> **Low confidence results.** Best score: ${topScore.toFixed(3)}. These results may not be relevant to your query.\n> Try more specific keywords or different phrasing.\n\n`
+        output += `> **Low confidence.** Best score: ${topScore.toFixed(3)}. Try more specific keywords.\n\n`
       }
 
-      for (let i = 0; i < sortedGroups.length; i++) {
-        const { best: r, chunks } = sortedGroups[i]
-        const score = (r._finalScore ?? 0).toFixed(3)
-        const indexLabel = args.searchAll ? ` [${r._index}]` : ""
-        const chunkNote = chunks.length > 1 ? ` (${chunks.length} matching sections)` : ""
-
-        // Rich metadata
-        const metaParts: string[] = []
-        if (r.language && r.language !== "unknown") metaParts.push(r.language)
-        if (r.heading_context) metaParts.push(`"${r.heading_context}"`)
-        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(", ")})` : ""
-
-        // Score breakdown
-        const breakdownParts: string[] = r._bm25Only
-          ? [`bm25: ${(r._bm25Component ?? 0).toFixed(2)}`]
-          : [`vec: ${(r._vectorScore ?? 0).toFixed(2)}`]
-        if (!r._bm25Only && r._bm25Component > 0.005) breakdownParts.push(`bm25: +${r._bm25Component.toFixed(2)}`)
-        if (r._keywordBonus > 0.005) breakdownParts.push(`kw: +${r._keywordBonus.toFixed(2)}`)
-        const breakdown = breakdownParts.join(", ")
-
-        // Matched keywords
-        const kwDisplay = r._matchedKeywords && r._matchedKeywords.length > 0
-          ? ` | matched: "${r._matchedKeywords.join('", "')}"`
-          : ""
-
-        output += `### ${i + 1}. ${r.file}${indexLabel}${chunkNote}\n`
-        output += `**Score:** ${score} (${breakdown}${kwDisplay})${metaLine}\n\n`
-        output += "```\n"
-        const content = r.content.length > 500 ? r.content.substring(0, 500) + "\n... (truncated)" : r.content
-        output += content
-        output += "\n```\n"
-
-        // Second-best chunk hint
-        if (chunks.length > 1) {
-          const second = chunks.find((c: any) => c !== r)
-          if (second) {
-            const secMeta: string[] = []
-            if (second.function_name) secMeta.push(`fn: ${second.function_name}`)
-            if (second.heading_context) secMeta.push(`"${second.heading_context}"`)
-            const secLabel = secMeta.length > 0 ? ` ${secMeta.join(", ")}` : ""
-            output += `\n*Also:${secLabel}*\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 (r.relatedContext && r.relatedContext.length > 0) {
-          output += "\n**Related Context:**\n"
-          for (const rel of r.relatedContext) {
-            const snippet = rel.content.length > 200
-              ? rel.content.substring(0, 200) + "..."
-              : rel.content
-            output += `- **${rel.file}** (${rel.relation}, via ${rel.via}, score: ${rel.score.toFixed(2)})\n`
-            output += `  \`\`\`\n  ${snippet}\n  \`\`\`\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`
+      }
 
-        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*${uniqueFiles} files (${totalChunks} chunks). Use Read tool to see full files.*`
+      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().*`
+
       return output
     } catch (error: any) {
       return `Search failed: ${error.message || String(error)}`