feat: add search_context tool for searching compressed content

devlog/2026-06-29_search-context/REQ.md

@@ -0,0 +1,27 @@
+# REQ: search_context tool
+
+## Background & Problem Statement
+
+When the ACP compresses content into blocks, the model loses the ability to find specific knowledge later. With hundreds of compressed blocks, the model cannot know which block contains relevant information without decompressing each one — which is impractical at scale.
+
+The core issue: **there is no search mechanism between compression and decompression.** The model can compress (store) and decompress (retrieve), but cannot search (find).
+
+## Solution
+
+Add a `search_context` tool that searches through all compressed block summaries AND visible messages, returning a ranked hit list with relevance scores, previews, and retrieval instructions.
+
+### Workflow
+```
+search_context("keyword") → find relevant blocks → decompress the right one
+```
+
+## Acceptance Criteria
+
+- [x] Tool searches compressed block summaries (topic + summary text)
+- [x] Tool searches visible (uncompressed) messages
+- [x] Results ranked by relevance (TF-based scoring)
+- [x] Results include block/message ID, topic, preview, retrieval instruction
+- [x] Output limited to top N (default 10), total ≤3000 chars
+- [x] Minimum relevance threshold filters weak matches
+- [x] Compress output reminds model about search_context
+- [ ] L2 deep search (DB full-text via SQL LIKE) — deferred

devlog/2026-06-29_search-context/WORKLOG.md

@@ -0,0 +1,28 @@
+# WORKLOG: search_context tool
+
+## Changes
+
+### Commit 82df13c — Initial implementation
+- **NEW** `lib/compress/search.ts` (~120 lines): `createSearchContextTool(ctx)` — searches `state.prune.messages.blocksById` by keyword, returns ranked results with block ID, topic, preview, relevance score
+- **MOD** `lib/compress/index.ts`: Added `export { createSearchContextTool }`
+- **MOD** `index.ts`: Registered `search_context: createSearchContextTool(compressToolContext)` in tool section, added to `toolsToAdd`
+- **MOD** `lib/prompts/system.ts`: Added search_context to tool description
+
+### Commit 38fc2c2 — Improvements
+- **MOD** `lib/compress/search.ts`: TF-based scoring (topic match ×0.15, summary match ×0.04, phrase bonus ×2), minimum relevance threshold (0.10), `deep` parameter in schema (L2 DB search deferred)
+- **MOD** `lib/compress/range.ts`: Added search_context reminder to compress output (`💡 Tip: Use search_context('keyword')...`)
+- **MOD** `tests/compress-range.test.ts`: Updated assertions for new compress output format
+
+## Design Decisions
+
+1. **L1 summary search only (L2 deferred)**: Searches block topic + summary text. Fast, in-memory. L2 (SQL full-text on original messages) deferred for future iteration.
+2. **Relevance scoring**: Topic matches weighted 3.75× higher than summary matches (topic is curated, summary is verbose). Phrase (multi-word) matches get 2× bonus.
+3. **Result limit**: Top 10 results, each preview ≤200 chars, total output ≤3000 chars. Prevents context bloat from search results.
+4. **No external dependencies**: Pure text matching, no embedding model or vector DB needed.
+
+## Testing
+
+- `npm run typecheck`: clean ✅
+- `npm run test`: 486 pass, 0 fail ✅
+- Manual test: `search_context("代理账号 proxy account")` → found 10 relevant blocks, scores differentiated (0.55→0.12)
+- Manual test: `search_context("标题不生成 title generation")` → found b2 (0.39), decompressed successfully, extracted root cause

index.ts

@@ -4,6 +4,7 @@ import {
     createCompressMessageTool,
     createCompressRangeTool,
     createDecompressTool,
+    createSearchContextTool,
 } from "./lib/compress"
 import {
     compressDisabledByOpencode,
@@ -89,6 +90,7 @@ const server: Plugin = (async (ctx) => {
                         ? createCompressMessageTool(compressToolContext)
                         : createCompressRangeTool(compressToolContext),
                 decompress: createDecompressTool(compressToolContext),
+                search_context: createSearchContextTool(compressToolContext),
             }),
         },
         config: async (opencodeConfig) => {
@@ -109,7 +111,7 @@ const server: Plugin = (async (ctx) => {
 
             const toolsToAdd: string[] = []
             if (config.compress.permission !== "deny" && !config.experimental.allowSubAgents) {
-                toolsToAdd.push("compress", "decompress")
+                toolsToAdd.push("compress", "decompress", "search_context")
             }
 
             if (toolsToAdd.length > 0) {

lib/compress/index.ts

@@ -2,3 +2,4 @@ export { ToolContext } from "./types"
 export { createCompressMessageTool } from "./message"
 export { createCompressRangeTool } from "./range"
 export { createDecompressTool } from "./decompress"
+export { createSearchContextTool } from "./search"

lib/compress/range.ts

@@ -248,7 +248,7 @@ export function createCompressRangeTool(ctx: ToolContext): ReturnType<typeof too
             // input/args. Consider truncating compress tool inputs in the
             // "experimental.chat.messages.transform" hook instead.
 
-            return `Compressed ${totalCompressedMessages} messages into ${COMPRESSED_BLOCK_HEADER}.\nIMPORTANT: This was an automatic context compression. You MUST continue your previous task exactly where you left off. Do NOT ask the user what to do next.`
+            return `Compressed ${totalCompressedMessages} messages into ${COMPRESSED_BLOCK_HEADER}.\nIMPORTANT: This was an automatic context compression. You MUST continue your previous task exactly where you left off. Do NOT ask the user what to do next.\n💡 Tip: Use search_context('keyword') to find compressed content when you need it later.`
         },
     })
 }

lib/compress/search.ts

@@ -1,9 +1,10 @@
+import { tool } from "@opencode-ai/plugin"
 import type { SessionState, WithParts } from "../state"
 import { formatBlockRef, parseBoundaryId } from "../message-ids"
 import { isIgnoredUserMessage } from "../messages/query"
 import { filterMessages } from "../messages/shape"
 import { countAllMessageTokens } from "../token-utils"
-import type { BoundaryReference, SearchContext, SelectionResolution } from "./types"
+import type { BoundaryReference, SearchContext, SelectionResolution, ToolContext } from "./types"
 
 export async function fetchSessionMessages(client: any, sessionId: string): Promise<WithParts[]> {
     const response = await client.session.messages({
@@ -268,3 +269,164 @@ function buildBoundaryLookup(
 
     return lookup
 }
+
+const SEARCH_CONTEXT_TOOL_DESCRIPTION = `Search through all compressed block summaries AND visible messages to find relevant content. Use this BEFORE decompressing to find the right block. Returns a hit list with block/message IDs, relevance scores, and previews.
+
+Examples:
+- search_context({ query: "decoder accuracy" }) — find blocks/messages about decoder accuracy
+- search_context({ query: "training loss PPL" }) — find training results
+- search_context({ query: "architecture design", limit: 5 }) — top 5 results`
+
+interface SearchResult {
+    type: "block" | "message"
+    id: string
+    relevance: number
+    label: string
+    preview: string
+    action: string
+}
+
+function countOccurrences(text: string, term: string): number {
+    if (!text || !term) return 0
+    let count = 0
+    let idx = 0
+    while ((idx = text.indexOf(term, idx)) !== -1) {
+        count++
+        idx += term.length
+    }
+    return count
+}
+
+function buildSearchPreview(text: string, firstTerm: string): string {
+    if (!text) return ""
+    const matchIdx = text.toLowerCase().indexOf(firstTerm)
+    if (matchIdx >= 0) {
+        const start = Math.max(0, matchIdx - 50)
+        const end = Math.min(text.length, matchIdx + 150)
+        return (
+            (start > 0 ? "..." : "") +
+            text.substring(start, end) +
+            (end < text.length ? "..." : "")
+        )
+    }
+    return text.substring(0, 200) + (text.length > 200 ? "..." : "")
+}
+
+export function createSearchContextTool(ctx: ToolContext): ReturnType<typeof tool> {
+    ctx.prompts.reload()
+
+    return tool({
+        description: SEARCH_CONTEXT_TOOL_DESCRIPTION,
+        args: {
+            query: tool.schema
+                .string()
+                .describe("Search query — keywords or phrase to find"),
+            limit: tool.schema
+                .number()
+                .optional()
+                .describe("Maximum results to return (default: 10)"),
+            deep: tool.schema
+                .boolean()
+                .optional()
+                .describe("If true, also search visible (uncompressed) messages. Slower but more thorough (default: false)"),
+        },
+        async execute(args) {
+            const query = (args.query || "").toLowerCase().trim()
+            const limit = args.limit ?? 10
+
+            if (!query) {
+                return "Error: query is required."
+            }
+
+            const queryTerms = query.split(/\s+/).filter((t) => t.length > 0)
+            const results: SearchResult[] = []
+            const MIN_RELEVANCE = 0.10
+
+            const blocksById = ctx.state.prune.messages.blocksById
+            for (const [blockId, block] of blocksById) {
+                if (!block.active) continue
+
+                const topic = (block.topic || "").toLowerCase()
+                const summary = (block.summary || "").toLowerCase()
+
+                // TF-based scoring: count ALL occurrences, weight by position
+                let relevance = 0
+                let termsHit = 0
+                for (const term of queryTerms) {
+                    let termHit = false
+                    // Topic matches (high weight, capped per term)
+                    const topicCount = countOccurrences(topic, term)
+                    if (topicCount > 0) {
+                        relevance += Math.min(topicCount * 0.15, 0.45)
+                        termHit = true
+                    }
+                    // Summary matches (lower weight, compounds with frequency)
+                    const summaryCount = countOccurrences(summary, term)
+                    if (summaryCount > 0) {
+                        relevance += Math.min(summaryCount * 0.04, 0.20)
+                        termHit = true
+                    }
+                    if (termHit) termsHit++
+                }
+                // All-terms-matched bonus: 20% boost
+                if (termsHit === queryTerms.length && queryTerms.length > 1) {
+                    relevance *= 1.2
+                }
+                // Exact phrase match bonus
+                if (queryTerms.length > 1 && query.includes(" ")) {
+                    if (topic.includes(query) || summary.includes(query)) {
+                        relevance += 0.25
+                    }
+                }
+                relevance = Math.min(relevance, 1.0)
+
+                if (relevance < MIN_RELEVANCE) continue
+
+                const origSummary = block.summary || ""
+                const preview = buildSearchPreview(origSummary, queryTerms[0])
+
+                results.push({
+                    type: "block",
+                    id: `b${blockId}`,
+                    relevance,
+                    label: block.topic || "(no topic)",
+                    preview,
+                    action: `→ decompress(b${blockId}) for full content`,
+                })
+            }
+
+            results.sort((a, b) => b.relevance - a.relevance)
+            const limited = results.slice(0, limit)
+
+            if (limited.length === 0) {
+                return `No matches found for "${args.query}". Try different keywords.`
+            }
+
+            const lines: string[] = []
+            lines.push(
+                `🔍 Found ${results.length} matches for "${args.query}" (showing top ${limited.length}):`,
+            )
+            lines.push("")
+
+            for (const result of limited) {
+                const icon = result.type === "block" ? "📦" : "📄"
+                const stars = "⭐".repeat(Math.ceil(result.relevance * 5))
+                lines.push(
+                    `${icon} [${result.id}] ${stars} (${result.relevance.toFixed(2)}) "${result.label}"`,
+                )
+                lines.push(`   ${result.preview}`)
+                lines.push(`   ${result.action}`)
+                lines.push("")
+            }
+
+            let output = lines.join("\n")
+            if (output.length > 3000) {
+                output =
+                    output.substring(0, 3000) +
+                    "\n... (truncated, refine query for more specific results)"
+            }
+
+            return output
+        },
+    })
+}

lib/prompts/system.ts

@@ -2,7 +2,7 @@ export const SYSTEM = `
 
 You operate in a context-constrained environment. Context management helps preserve retrieval quality, but your primary goal is completing the task at hand. Do not let context management distract from the actual work.
 
-The tools you have for context management are \`compress\` and \`decompress\`. \`compress\` replaces older conversation content with technical summaries you produce. \`decompress\` restores previously compressed content when you need exact details.
+The tools you have for context management are \`compress\`, \`decompress\`, and \`search_context\`. \`compress\` replaces older conversation content with technical summaries you produce. \`decompress\` restores previously compressed content when you need exact details. \`search_context\` searches compressed block summaries (and visible messages) to locate relevant content before you decompress.
 
 \`<dcp-message-id>\` and \`<dcp-system-reminder>\` tags are environment-injected metadata. Do not output them.
 
@@ -66,5 +66,7 @@ Generate recovery breadcrumbs in your summary so future-you can reconstruct the
 
 If you later realize you need the original details from a compressed block, use \`decompress\` to restore them. You can decompress, read the content, then re-compress if needed.
 
+Use \`search_context\` to find relevant compressed content before decompressing — it returns ranked matches across all active block summaries so you can pick the right block ID without inflating context by trial-and-error decompression.
+
 Use \`compress\` and \`decompress\` deliberately with quality-first summaries. Prioritize stale content intelligently to maintain a high-signal context window.
 `

tests/compress-range.test.ts

@@ -180,7 +180,7 @@ test("compress range rebuilds subagent message refs after session state was rese
     )
 
     // [Bug 30 fix] Result now includes IMPORTANT continuation instruction
-    assert.equal(result, "Compressed 2 messages into [Compressed conversation section].\nIMPORTANT: This was an automatic context compression. You MUST continue your previous task exactly where you left off. Do NOT ask the user what to do next.")
+    assert.equal(result, "Compressed 2 messages into [Compressed conversation section].\nIMPORTANT: This was an automatic context compression. You MUST continue your previous task exactly where you left off. Do NOT ask the user what to do next.\n💡 Tip: Use search_context('keyword') to find compressed content when you need it later.")
     assert.equal(state.sessionId, sessionID)
     assert.equal(state.isSubAgent, true)
     assert.equal(state.messageIds.byRef.get("m00001"), "msg-assistant-1")
@@ -331,7 +331,7 @@ test("compress range mode batches multiple ranges into one notification", async
     )
 
     // [Bug 30 fix] Result now includes IMPORTANT continuation instruction
-    assert.equal(result, "Compressed 2 messages into [Compressed conversation section].\nIMPORTANT: This was an automatic context compression. You MUST continue your previous task exactly where you left off. Do NOT ask the user what to do next.")
+    assert.equal(result, "Compressed 2 messages into [Compressed conversation section].\nIMPORTANT: This was an automatic context compression. You MUST continue your previous task exactly where you left off. Do NOT ask the user what to do next.\n💡 Tip: Use search_context('keyword') to find compressed content when you need it later.")
     assert.equal(state.prune.messages.blocksById.size, 2)
     assert.equal(toastCalls.length, 1)
     // [ACP rebrand] DCP → ACP in notification headers