@comfanion/usethis_search 4.2.0-dev.4 → 4.3.0-dev.1

package/tools/search.ts

@@ -178,47 +178,70 @@ function parseFilter(filter: string): {
 }
 
 export default tool({
-  description: `Search the codebase semantically OR attach specific chunks/files to workspace.
+  description: `Search codebase and automatically attach relevant context to workspace.
 
-Three modes:
-1. Semantic search (query) - Find relevant code by meaning
-2. Direct chunk attach (chunkId) - Attach specific chunk by ID
-3. File attach (path) - Attach all chunks from a file
+Accepts any query - semantic search, file path, or chunk ID:
+- "authentication logic" → finds relevant code
+- "docs/architecture.md" → attaches file
+- "src/auth.ts:chunk-5" → attaches specific chunk
 
-Available indexes:
-- "code" (default) - Source code files (*.js, *.ts, *.py, *.go, etc.)
-- "docs" - Documentation files (*.md, *.txt, etc.)
-- searchAll: true - Search across all indexes
+Results are optimized for context - top chunks auto-attached with expanded context 
+(related code, imports, class methods).
+
+IMPORTANT: Workspace has limited token budget. Use workspace_forget() to remove 
+irrelevant files or old searches before adding new context.
+
+Choose index based on what you're looking for:
+- index: "code" → search source code
+- index: "docs" → search documentation  
+- searchAll: true → search everywhere
 
 Examples:
 - search({ query: "authentication logic" })
 - search({ query: "how to deploy", index: "docs" })
-- search({ query: "tenant management", filter: "internal/domain/" })
-- search({ chunkId: "src/auth.ts:chunk-5" })
-- search({ path: "docs/architecture.md" })
-- search({ path: "src/auth.ts", index: "code" })`,
+- search({ query: "docs/prd.md" })  // attach file
+- search({ query: "internal/domain/", filter: "*.go" })`,
 
   args: {
-    query: tool.schema.string().optional().describe("Semantic search query describing what you're looking for"),
-    chunkId: tool.schema.string().optional().describe("Specific chunk ID to attach (e.g. 'src/auth.ts:chunk-5')"),
-    path: tool.schema.string().optional().describe("File path to attach all chunks from (e.g. 'docs/architecture.md')"),
-    index: tool.schema.string().optional().default("code").describe("Index to search: code, docs"),
-    limit: tool.schema.number().optional().describe("Number of results (default from config, typically 10)"),
-    searchAll: tool.schema.boolean().optional().default(false).describe("Search all indexes instead of just one"),
-    filter: tool.schema.string().optional().describe("Filter results by path or language. Examples: 'internal/domain/', '*.go', 'internal/**/*.go', 'service'"),
+    query: tool.schema.string().describe("What to search: semantic query, file path, or chunk ID"),
+    index: tool.schema.string().optional().default("code").describe("Where to search: 'code', 'docs', or leave empty for auto-detect"),
+    limit: tool.schema.number().optional().describe("Max results (default: 10)"),
+    searchAll: tool.schema.boolean().optional().default(false).describe("Search all indexes instead of one"),
+    filter: tool.schema.string().optional().describe("Filter by path/language: 'internal/domain/', '*.go', 'service'"),
   },
 
   async execute(args) {
     const projectRoot = process.cwd()
 
     try {
-      // Validate: exactly one of query, chunkId, or path must be specified
-      const modes = [args.query, args.chunkId, args.path].filter(x => x !== undefined)
-      if (modes.length === 0) {
-        return `Error: Must specify one of: query (semantic search), chunkId (direct attach), or path (file attach)\n\nExamples:\n- search({ query: "authentication" })\n- search({ chunkId: "src/auth.ts:chunk-5" })\n- search({ path: "docs/architecture.md" })`
+      if (!args.query) {
+        return `Error: query is required\n\nExamples:\n- search({ query: "authentication logic" })\n- search({ query: "docs/architecture.md" })\n- search({ query: "src/auth.ts:chunk-5" })`
+      }
+
+      // Auto-detect mode from query
+      let mode: "chunkId" | "path" | "semantic"
+      let chunkId: string | undefined
+      let filePath: string | undefined
+      let semanticQuery: string | undefined
+
+      // 1. Check if it's a chunk ID (contains ":chunk-")
+      if (args.query.includes(":chunk-")) {
+        mode = "chunkId"
+        chunkId = args.query
+      }
+      // 2. Check if it's a file path (has extension or starts with common paths)
+      else if (
+        args.query.match(/\.(md|ts|js|go|py|tsx|jsx|rs|java|kt|swift|txt|yaml|json|yml|toml)$/i) ||
+        args.query.match(/^(src|docs|internal|pkg|lib|app|pages|components|api)\//i) ||
+        args.query.includes("/")
+      ) {
+        mode = "path"
+        filePath = args.query
       }
-      if (modes.length > 1) {
-        return `Error: Specify only ONE of: query, chunkId, or path (got ${modes.length})`
+      // 3. Otherwise, it's a semantic search
+      else {
+        mode = "semantic"
+        semanticQuery = args.query
       }
 
       // Load config defaults (parsed from vectorizer.yaml)
@@ -234,23 +257,23 @@ Examples:
       // ══════════════════════════════════════════════════════════════════════
       // MODE 1: Direct chunk attach by chunkId
       // ══════════════════════════════════════════════════════════════════════
-      if (args.chunkId) {
+      if (mode === "chunkId") {
         const indexer = await getIndexer(projectRoot, indexName)
         try {
-          const chunk = await indexer.findChunkById(args.chunkId)
+          const chunk = await indexer.findChunkById(chunkId!)
           if (!chunk) {
-            return `Chunk "${args.chunkId}" not found in index "${indexName}".\n\nMake sure:\n1. The file is indexed\n2. The chunk ID is correct (format: "path:chunk-N")\n3. You're searching the right index`
+            return `Chunk "${chunkId}" not found in index "${indexName}".\n\nMake sure:\n1. The file is indexed\n2. The chunk ID is correct (format: "path:chunk-N")\n3. You're searching the right index`
           }
 
           // Attach to workspace
           workspaceCache.attach({
-            chunkId: args.chunkId,
+            chunkId: chunkId!,
             path: chunk.file,
             content: chunk.content,
             chunkIndex: chunk.chunk_index ?? 0,
             role: "manual",
             attachedAt: Date.now(),
-            attachedBy: `direct:${args.chunkId}`,
+            attachedBy: `direct:${chunkId}`,
             metadata: {
               language: chunk.language,
               function_name: chunk.function_name,
@@ -263,8 +286,8 @@ Examples:
 
           workspaceCache.save().catch(() => {})
 
-          const entry = workspaceCache.get(args.chunkId)!
-          return `✓ Attached chunk to workspace\n\nChunk: ${args.chunkId}\nFile: ${chunk.file}\nTokens: ${entry.tokens.toLocaleString()}\nLanguage: ${chunk.language}\nLines: ${chunk.start_line}-${chunk.end_line}\n\nWorkspace: ${workspaceCache.size} chunks, ${workspaceCache.totalTokens.toLocaleString()} tokens`
+          const entry = workspaceCache.get(chunkId!)!
+          return `✓ Attached chunk to workspace\n\nChunk: ${chunkId}\nFile: ${chunk.file}\nTokens: ${entry.tokens.toLocaleString()}\nLanguage: ${chunk.language}\nLines: ${chunk.start_line}-${chunk.end_line}\n\nWorkspace: ${workspaceCache.size} chunks, ${workspaceCache.totalTokens.toLocaleString()} tokens`
         } finally {
           releaseIndexer(projectRoot, indexName)
         }
@@ -273,27 +296,27 @@ Examples:
       // ══════════════════════════════════════════════════════════════════════
       // MODE 2: File attach by path (all chunks)
       // ══════════════════════════════════════════════════════════════════════
-      if (args.path) {
+      if (mode === "path") {
         const indexer = await getIndexer(projectRoot, indexName)
         try {
-          const chunks = await indexer.findChunksByPath(args.path)
+          const chunks = await indexer.findChunksByPath(filePath!)
           if (chunks.length === 0) {
-            return `No chunks found for file "${args.path}" in index "${indexName}".\n\nMake sure:\n1. The file exists and is indexed\n2. The path is correct (relative to project root)\n3. You're searching the right index\n\nRun: bunx usethis_search reindex`
+            return `No chunks found for file "${filePath}" in index "${indexName}".\n\nMake sure:\n1. The file exists and is indexed\n2. The path is correct (relative to project root)\n3. You're searching the right index\n\nRun: bunx usethis_search reindex`
           }
 
           // Attach all chunks to workspace
           let totalTokens = 0
           for (const chunk of chunks) {
-            const chunkId = chunk.chunk_id || `${args.path}:chunk-${chunk.chunk_index ?? 0}`
+            const chunkIdForChunk = chunk.chunk_id || `${filePath}:chunk-${chunk.chunk_index ?? 0}`
             
             workspaceCache.attach({
-              chunkId,
-              path: args.path,
+              chunkId: chunkIdForChunk,
+              path: filePath!,
               content: chunk.content,
               chunkIndex: chunk.chunk_index ?? 0,
               role: "manual",
               attachedAt: Date.now(),
-              attachedBy: `file:${args.path}`,
+              attachedBy: `file:${filePath}`,
               metadata: {
                 language: chunk.language,
                 function_name: chunk.function_name,
@@ -304,13 +327,13 @@ Examples:
               },
             })
 
-            const entry = workspaceCache.get(chunkId)!
+            const entry = workspaceCache.get(chunkIdForChunk)!
             totalTokens += entry.tokens
           }
 
           workspaceCache.save().catch(() => {})
 
-          return `✓ Attached file to workspace\n\nFile: ${args.path}\nChunks: ${chunks.length}\nTokens: ${totalTokens.toLocaleString()}\nLanguage: ${chunks[0].language}\n\nWorkspace: ${workspaceCache.size} chunks, ${workspaceCache.totalTokens.toLocaleString()} tokens`
+          return `✓ Attached file to workspace\n\nFile: ${filePath}\nChunks: ${chunks.length}\nTokens: ${totalTokens.toLocaleString()}\nLanguage: ${chunks[0].language}\n\nWorkspace: ${workspaceCache.size} chunks, ${workspaceCache.totalTokens.toLocaleString()} tokens`
         } finally {
           releaseIndexer(projectRoot, indexName)
         }
@@ -352,7 +375,7 @@ Examples:
         for (const idx of indexes) {
           const indexer = await getIndexer(projectRoot, idx)
           try {
-            const results = await indexer.search(args.query, limit, includeArchived, searchOptions)
+            const results = await indexer.search(semanticQuery!, limit, includeArchived, searchOptions)
             allResults.push(...results.map((r: any) => ({ ...r, _index: idx })))
           } finally {
             releaseIndexer(projectRoot, idx)
@@ -390,14 +413,14 @@ Examples:
 
           if (available.length > 0) {
             const list = available.map(i => `"${i}"`).join(", ")
-            return `Index "${indexName}" not found. Available indexes: ${list}.\n\nTry: search({ query: "${args.query}", index: "${available[0]}" })\nOr search all: search({ query: "${args.query}", searchAll: true })`
+            return `Index "${indexName}" not found. Available indexes: ${list}.\n\nTry: search({ query: "${semanticQuery}", index: "${available[0]}" })\nOr search all: search({ query: "${semanticQuery}", searchAll: true })`
           }
           return `No indexes found. The codebase needs to be indexed first.\n\nRun the CLI: bunx usethis_search reindex`
         }
 
         const indexer = await getIndexer(projectRoot, indexName)
         try {
-          const results = await indexer.search(args.query, limit, includeArchived, searchOptions)
+          const results = await indexer.search(semanticQuery!, limit, includeArchived, searchOptions)
           allResults = results.map((r: any) => ({ ...r, _index: indexName }))
         } finally {
           releaseIndexer(projectRoot, indexName)
@@ -411,20 +434,58 @@ Examples:
       })
 
       // ── Filter — apply path/language constraints from `filter` param ───────
+      // Strategy: Try strict filter first, fallback to relaxed if too few results
+      const unfilteredResults = [...allResults]
+      let filterApplied = false
+      let filterRelaxed = false
+
       if (filterParsed.pathPrefix) {
         const prefix = filterParsed.pathPrefix
-        allResults = allResults.filter(r => r.file && r.file.startsWith(prefix))
+        const strictFiltered = allResults.filter(r => r.file && r.file.startsWith(prefix))
+        
+        // Fallback: if strict gives < 3 results, try "contains" instead of "startsWith"
+        if (strictFiltered.length < 3 && allResults.length > strictFiltered.length) {
+          const relaxedFiltered = allResults.filter(r => r.file && r.file.includes(prefix))
+          if (relaxedFiltered.length > strictFiltered.length) {
+            allResults = relaxedFiltered
+            filterRelaxed = true
+          } else {
+            allResults = strictFiltered
+          }
+        } else {
+          allResults = strictFiltered
+        }
+        filterApplied = true
       }
+      
       if (filterParsed.pathContains) {
         const needle = filterParsed.pathContains.toLowerCase()
         allResults = allResults.filter(r => r.file && r.file.toLowerCase().includes(needle))
+        filterApplied = true
       }
+      
       if (filterParsed.language) {
-        allResults = allResults.filter(r => !r.language || r.language === filterParsed.language || r.language === "unknown")
+        const strictFiltered = allResults.filter(r => r.language === filterParsed.language)
+        
+        // Fallback: if strict language filter gives < 3 results, include "unknown" language
+        if (strictFiltered.length < 3 && allResults.length > strictFiltered.length) {
+          const relaxedFiltered = allResults.filter(r => 
+            !r.language || r.language === filterParsed.language || r.language === "unknown"
+          )
+          if (relaxedFiltered.length > strictFiltered.length) {
+            allResults = relaxedFiltered
+            filterRelaxed = true
+          } else {
+            allResults = strictFiltered
+          }
+        } else {
+          allResults = strictFiltered
+        }
+        filterApplied = true
       }
 
       // ── Reranking — boost results where query keywords appear in text ──────
-      const queryKeywords = args.query.toLowerCase().split(/\s+/).filter((w: string) => w.length > 2)
+      const queryKeywords = semanticQuery!.toLowerCase().split(/\s+/).filter((w: string) => w.length > 2)
       for (const r of allResults) {
         const isBM25Only = !!r._bm25Only
         const vectorScore = r._distance != null ? Math.max(0, 1 - r._distance / 2) : 0
@@ -454,7 +515,7 @@ Examples:
        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 })`
+         return `No results found in ${scope}${filterNote} for: "${semanticQuery}" (min score: ${minScore})\n\nTry:\n- Different keywords or phrasing\n- Remove or broaden the filter\n- search({ query: "...", searchAll: true })`
        }
 
        // ══════════════════════════════════════════════════════════════════════
@@ -479,15 +540,15 @@ Examples:
          // Attach main chunk
          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,
+          workspaceCache.attach({
+            chunkId,
+            path: chunk.file,
+            content: chunk.content,
+            chunkIndex: chunk.index ?? 0,
+            role: "search-main",
+            attachedAt: Date.now(),
+            attachedBy: semanticQuery!,
+            score: chunk._finalScore,
            metadata: {
              language: chunk.language,
              function_name: chunk.function_name,
@@ -511,14 +572,14 @@ Examples:
              // Check budget before adding
              if (workspaceCache.size >= wsConfig.maxChunks) break
              
-             workspaceCache.attach({
-               chunkId: expChunkId,
-               path: expChunk.file,
-               content: expChunk.content,
-               chunkIndex: expChunk.chunk_index ?? 0,
-               role: "search-context",
-               attachedAt: Date.now(),
-               attachedBy: `${args.query} (${reason})`,
+              workspaceCache.attach({
+                chunkId: expChunkId,
+                path: expChunk.file,
+                content: expChunk.content,
+                chunkIndex: expChunk.chunk_index ?? 0,
+                role: "search-context",
+                attachedAt: Date.now(),
+                attachedBy: `${semanticQuery} (${reason})`,
                score: chunk._finalScore * 0.9, // Slightly lower score than main
                metadata: {
                  language: expChunk.language,
@@ -550,14 +611,14 @@ Examples:
              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})`,
+              workspaceCache.attach({
+                chunkId: relChunkId,
+                path: rel.file,
+                content: rel.content,
+                chunkIndex: rel.index ?? 0,
+                role: "search-graph",
+                attachedAt: Date.now(),
+                attachedBy: `${semanticQuery} (${rel.relation} from ${chunkId})`,
                score: rel.score,
                metadata: {
                  language: rel.language,
@@ -590,12 +651,16 @@ Examples:
       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: "${args.query}" (${scope}${filterLabel})\n\n`
+      let output = `## Search: "${semanticQuery}" (${scope}${filterLabel})\n\n`
 
       if (hasBM25Only) {
         output += `> **BM25-only mode** -- vector embeddings not yet available. Quality will improve after embedding completes.\n\n`
       }
 
+      if (filterRelaxed) {
+        output += `> **Filter relaxed.** Strict filter gave too few results. Showing broader matches.\n\n`
+      }
+
       if (topScore < 0.45) {
         output += `> **Low confidence.** Best score: ${topScore.toFixed(3)}. Try more specific keywords.\n\n`
       }

package/tools/workspace.ts

@@ -155,102 +155,77 @@ export const workspace_list = tool({
   },
 })
 
-// ── workspace.attach ────────────────────────────────────────────────────────
+// ── workspace.forget ────────────────────────────────────────────────────────
 
-export const workspace_attach = tool({
-  description: `Manually attach a file to workspace context as a single chunk. The file will be visible in context injection without needing read().`,
+export const workspace_forget = tool({
+  description: `Remove chunks from workspace context to optimize context size and focus.
 
-  args: {
-    filePath: tool.schema.string().describe("Relative file path to attach (e.g. 'src/auth/login.ts')"),
-  },
+IMPORTANT: Regularly clean up workspace by removing irrelevant files or old search results. 
+This keeps context focused and prevents token budget overflow.
 
-  async execute(args) {
-    const projectRoot = process.cwd()
-
-    // Read file content
-    try {
-      const fullPath = path.join(projectRoot, args.filePath)
-      const content = await fs.readFile(fullPath, "utf-8")
-
-      // Generate chunkId for manual attachment: "path:chunk-0"
-      const chunkId = `${args.filePath}:chunk-0`
-
-      // Check if already attached
-      if (workspaceCache.has(args.filePath)) {
-        const existing = workspaceCache.getChunksByPath(args.filePath)
-        if (existing.length > 0) {
-          const first = existing[0]
-          const totalTokens = existing.reduce((sum, c) => sum + c.tokens, 0)
-          return `File "${args.filePath}" is already in workspace (${existing.length} chunk${existing.length > 1 ? "s" : ""}).\nTokens: ${totalTokens.toLocaleString()} | Role: ${first.role} | Score: ${first.score?.toFixed(3) ?? "n/a"}`
-        }
-      }
+Auto-detects what to remove based on input:
+- Chunk ID: "src/auth.ts:chunk-5"
+- File path: "docs/architecture.md" (removes ALL chunks)
+- Search query: "authentication logic" (removes chunks from this search)
+- Age: "5" (removes chunks older than 5 minutes)
 
-      workspaceCache.attach({
-        chunkId,
-        path: args.filePath,
-        content,
-        chunkIndex: 0,
-        role: "manual",
-        attachedAt: Date.now(),
-        attachedBy: "manual",
-      })
-
-      const entry = workspaceCache.get(chunkId)!
-      return `Attached "${args.filePath}" to workspace as single chunk.\nChunkId: ${chunkId}\nTokens: ${entry.tokens.toLocaleString()}\nWorkspace total: ${workspaceCache.totalTokens.toLocaleString()} tokens (${workspaceCache.size} chunks)`
-    } catch (error: any) {
-      return `Failed to attach "${args.filePath}": ${error.message || String(error)}`
-    }
-  },
-})
-
-// ── workspace.detach ────────────────────────────────────────────────────────
-
-export const workspace_detach = tool({
-  description: `Remove chunks from workspace context. Can detach by chunkId, by file path (removes ALL chunks of that file), by search query, or by age.`,
+Examples:
+- workspace_forget({ what: "docs/prd.md" })
+- workspace_forget({ what: "5" })  // older than 5 min
+- workspace_forget({ what: "src/auth.ts:chunk-3" })`,
 
   args: {
-    chunkId: tool.schema.string().optional().describe("Specific chunk ID to remove (e.g. 'src/auth.ts:chunk-5')"),
-    filePath: tool.schema.string().optional().describe("File path to remove (removes ALL chunks of that file)"),
-    query: tool.schema.string().optional().describe("Remove all chunks attached by this search query"),
-    olderThan: tool.schema.number().optional().describe("Remove chunks older than N minutes"),
+    what: tool.schema.string().describe("What to forget: chunk ID, file path, search query, or age in minutes"),
   },
 
   async execute(args) {
     let removed = 0
-
-    if (args.chunkId) {
-      // Detach specific chunk by chunkId
-      const entry = workspaceCache.get(args.chunkId)
-      
+    
+    // Auto-detect what to remove
+    // 1. Check if it's a chunk ID (contains ":chunk-")
+    if (args.what.includes(":chunk-")) {
+      const entry = workspaceCache.get(args.what)
       if (!entry) {
-        return `Chunk "${args.chunkId}" not found in workspace.`
+        return `Chunk "${args.what}" not found in workspace.`
       }
-      
-      removed = workspaceCache.detach(args.chunkId) ? 1 : 0
+      removed = workspaceCache.detach(args.what) ? 1 : 0
       if (removed === 0) {
-        return `Failed to remove chunk "${args.chunkId}".`
+        return `Failed to remove chunk "${args.what}".`
       }
-    } else if (args.filePath) {
-      // Detach all chunks of a file
-      const fileChunks = workspaceCache.getChunksByPath(args.filePath)
-      
+      return `Removed chunk "${args.what}" from workspace.\nWorkspace: ${workspaceCache.size} chunks, ${workspaceCache.totalTokens.toLocaleString()} tokens`
+    }
+    
+    // 2. Check if it's a number (age in minutes)
+    const ageMatch = args.what.match(/^(\d+)$/)
+    if (ageMatch) {
+      const minutes = parseInt(ageMatch[1], 10)
+      removed = workspaceCache.detachOlderThan(minutes * 60 * 1000)
+      return `Removed ${removed} chunk(s) older than ${minutes} minutes.\nWorkspace: ${workspaceCache.size} chunks, ${workspaceCache.totalTokens.toLocaleString()} tokens`
+    }
+    
+    // 3. Check if it's a file path (has extension or common path prefixes)
+    if (
+      args.what.match(/\.(md|ts|js|go|py|tsx|jsx|rs|java|kt|swift|txt|yaml|json|yml|toml)$/i) ||
+      args.what.match(/^(src|docs|internal|pkg|lib|app|pages|components|api)\//i) ||
+      args.what.includes("/")
+    ) {
+      const fileChunks = workspaceCache.getChunksByPath(args.what)
       if (fileChunks.length === 0) {
-        return `File "${args.filePath}" not found in workspace.`
+        return `File "${args.what}" not found in workspace.`
       }
-      
-      removed = workspaceCache.detachByPath(args.filePath)
+      removed = workspaceCache.detachByPath(args.what)
       if (removed === 0) {
-        return `Failed to remove chunks from "${args.filePath}".`
+        return `Failed to remove chunks from "${args.what}".`
       }
-    } else if (args.query) {
-      removed = workspaceCache.detachByQuery(args.query)
-    } else if (args.olderThan) {
-      removed = workspaceCache.detachOlderThan(args.olderThan * 60 * 1000)
-    } else {
-      return `Specify chunkId, filePath, query, or olderThan to detach chunks.`
+      return `Removed ${removed} chunk(s) from "${args.what}".\nWorkspace: ${workspaceCache.size} chunks, ${workspaceCache.totalTokens.toLocaleString()} tokens`
     }
-
-    return `Removed ${removed} chunk(s) from workspace.\nWorkspace: ${workspaceCache.size} chunks, ${workspaceCache.totalTokens.toLocaleString()} tokens`
+    
+    // 4. Otherwise, treat as search query
+    removed = workspaceCache.detachByQuery(args.what)
+    if (removed === 0) {
+      return `No chunks found attached by query "${args.what}".\n\nTip: Use workspace_list() to see what's in workspace.`
+    }
+    return `Removed ${removed} chunk(s) from search "${args.what}".\nWorkspace: ${workspaceCache.size} chunks, ${workspaceCache.totalTokens.toLocaleString()} tokens`
   },
 })