feat(web_search): SearXNG-backed web_search tool + Docker sidecar (#24)

* feat(web_search): add SearXNG-backed web_search tool + compose sidecar

Gives the agent local-first web search with no cloud API or keys, matching the
transcribe/vision zero-setup pattern.

Tool (cmd/odek/web_search_tool.go):
- Native Go tool querying a self-hosted SearXNG JSON API; returns ranked
  results (title/url/snippet/engine) + direct answers, capped by max_results.
- Output wrapped as untrusted content (SERP snippets can carry injection).
- Gated as network_egress (prompt in restricted, allow in godmode), consistent
  with browser/http_batch. The backend URL is fixed config, not agent-supplied,
  so the tool has no SSRF surface (only a query string is accepted).
- Registered only when web_search.base_url is set, so plain installs without a
  SearXNG instance don't see a dead tool.

Config (internal/config):
- WebSearchConfig{BaseURL, Categories, Language, MaxResults, Timeout} threaded
  end-to-end (FileConfig, ResolvedConfig, resolveWebSearch, overlayFile).

Wiring (cmd/odek):
- builtinTools' growing positional config params (Transcription, Vision) are
  bundled into a toolConfig struct to stop per-tool signature churn; all ~10
  call sites updated. web_search is threaded into run/serve/repl/telegram/
  schedule/subagent/mcp.

Docker:
- New `searxng` compose sidecar (pinned image), co-starting with every profile,
  internal-only (no host port), with depends_on wired on each odek service.
- docker/searxng/settings.yml enables the JSON API and disables the anti-bot
  limiter, so no Redis/Valkey is needed. SEARXNG_SECRET added to .env.example.
- Both bundled configs set web_search.base_url=http://searxng:8080.

Tests: hermetic httptest SearXNG mock covering happy path, max_results override
vs config cap, untrusted wrapping, JSON-disabled 403, unreachable backend,
policy denial, empty query, schema; resolveWebSearch defaults/merge. Full suite
green under -race.

Docs: README, SECURITY, CHEATSHEET, CONFIG, TELEGRAM, docker/README,
DOCKER_COMPOSE_USER_GUIDE.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(web_search): address code-review findings (answers, SSRF, secret, cold-start)

Code review of the SearXNG integration surfaced four actionable issues; fixes:

#2 (confirmed) — answers parsing emitted raw answer-object JSON. SearXNG
`answers` are objects ({"answer":"...","url":...,"template":...}), not bare
strings, so strings.Trim(rawJSON,'"') left the {...} blob intact. Decode the
`answer` field out of each object instead (also drops the fragile Trim). The
test mock used a string array, masking this — corrected to objects.

#3 (defense-in-depth) — the http.Client had no CheckRedirect. A compromised
or misconfigured SearXNG could 3xx the client toward an internal/metadata
endpoint (SSRF). Install the same per-hop re-classification guard browser and
http_batch use, capped at 10 hops. New TestWebSearch_RedirectToInternalBlocked.

#1 (hardening) — the mounted settings.yml hardcoded secret_key
"change-me-in-dot-env". Deeper tracing showed SEARXNG_SECRET *does* override
the file at app load (searx/settings_defaults.py environ_name), so the env
wiring worked — but the placeholder defeated SearXNG's built-in "secret_key
is not changed" warning, which only fires for the canonical "ultrasecretkey".
Switch the placeholder + the compose env fallback to "ultrasecretkey" so an
unset secret is loudly flagged rather than silently weak. Comments/.env.example
corrected to describe the real (app-load) override mechanism.

#4 (reliability) — `depends_on: [searxng]` only waits for container start, so
the first web_search after `compose up` could race SearXNG readiness. Rather
than a Docker healthcheck (whose probe tooling I can't verify in the upstream
image — a broken probe would deadlock odek startup), make the tool resilient:
retry only on ECONNREFUSED (the precise "up but not yet listening" signal),
2 extra attempts with a 1s backoff. Timeouts / genuine-down fail fast.

#5 (overlay whole-pointer replace) intentionally deferred — it is consistent
with the existing Skills/Memory/Transcription/Vision merge behavior; fixing
only web_search would be inconsistent.

Full suite green under -race; vet/gofmt clean; compose config validates.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs(web_search): surface in README + add standalone SearXNG recipe

Close two documentation gaps from the feature review:

- README discoverability: web_search was only mentioned in the prompt-injection
  paragraph and absent from the feature list. Add a "🌐 Local Web Search"
  strategic-feature blurb linking to the CHEATSHEET config reference.
- Non-Docker path: the CHEATSHEET only said "run SearXNG yourself" with no
  recipe. Add a concrete `docker run` snippet (reusing the repo's ready-made
  docker/searxng/settings.yml), the matching odek config, and the two settings
  that matter (search.formats json + limiter off) for bring-your-own configs.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(web_search): vprotocol auto-repair — tolerant answer decode + doc consistency

vprotocol v5.2.7 verification of the feat/searxng-web-search branch. Three
confirmed findings repaired; others refuted (redirect hop-count matches the
httpBatch pattern; :ro mount is non-fatal per the SearXNG entrypoint; all
settings.yml keys verified valid).

F1 (robustness) — the typed `answers []struct{Answer string}` decode coupled
the critical `results` parse to the answers shape: a non-string "answer" value
(or any foreign answer type) would fail the whole json.Unmarshal and drop ALL
results. Restore the original immunity by keeping answers as []json.RawMessage
and decoding each element tolerantly — a non-conforming answer is skipped, never
fatal. New TestWebSearch_HeterogeneousAnswersDoNotLoseResults locks it in.

F2 (consistency) — the CHEATSHEET standalone recipe used searxng/searxng:latest
while compose pins 2026.6.8-f3fab143b. Pin the recipe to the same tag.

F3 (docs) — the standalone recipe's `$PWD/docker/searxng/...` volume path
assumed the repo root without saying so. State "run from the repo root".

Full suite green under -race; vet/gofmt clean; compose validates.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: jkyberneees

README.md

@@ -36,7 +36,7 @@ odek is not a framework. It's a **runtime** — the smallest possible surface ar
 Every session can run in an isolated Docker container: no network, no host mounts beyond the working directory, zero capabilities, destroyed on exit. `odek serve` enables the sandbox **by default**; `odek run` keeps it opt-in but warns when running unsandboxed. `--ctx` files are auto-injected into the container at `/workspace/`. Full security model in [docs/SANDBOXING.md](docs/SANDBOXING.md).
 
 ### 🛡️ Prompt-Injection-Aware
-External content the agent ingests (`browser`, `read_file`, `shell`, `search_files`, `multi_grep`, `transcribe`, `vision`, `session_search`, MCP tools) is wrapped in per-call nonce'd `<untrusted_content>` boundaries so the model can distinguish data from instructions. Redirect hops are re-classified (`browser`/`http_batch`), MCP tool descriptions are scanned for injection at registration, and the MCP error channel is wrapped too. The danger classifier resists 8 known shell-evasion tricks (`$()`, backticks, `$IFS`, `command`/`exec`, `\rm`, basenamed absolute paths). Approvers engage friction mode after 3 same-class approvals in 60 s. Memory episodes from tainted sessions are stored but never auto-replayed. Skill auto-save tracks provenance and pins untrusted suggestions for explicit `odek skill promote`. `odek audit <session-id>` surfaces every ingest + per-turn divergence heuristic. Full threat model in [docs/SECURITY.md](docs/SECURITY.md).
+External content the agent ingests (`browser`, `read_file`, `shell`, `search_files`, `multi_grep`, `transcribe`, `vision`, `web_search`, `session_search`, MCP tools) is wrapped in per-call nonce'd `<untrusted_content>` boundaries so the model can distinguish data from instructions. Redirect hops are re-classified (`browser`/`http_batch`), MCP tool descriptions are scanned for injection at registration, and the MCP error channel is wrapped too. The danger classifier resists 8 known shell-evasion tricks (`$()`, backticks, `$IFS`, `command`/`exec`, `\rm`, basenamed absolute paths). Approvers engage friction mode after 3 same-class approvals in 60 s. Memory episodes from tainted sessions are stored but never auto-replayed. Skill auto-save tracks provenance and pins untrusted suggestions for explicit `odek skill promote`. `odek audit <session-id>` surfaces every ingest + per-turn divergence heuristic. Full threat model in [docs/SECURITY.md](docs/SECURITY.md).
 
 ### 🧩 Sub-Agent Delegation
 Parallel OS-process sub-agents via `delegate_tasks`. True isolation — each sub-agent is a fresh `odek subagent` process with its own config, tools, and termination timeout. Up to 8 concurrent workers. [docs/SUBAGENTS.md](docs/SUBAGENTS.md)
@@ -74,6 +74,9 @@ Attach files to any prompt with `--ctx` / `-c` (CLI), `@filename` inline referen
 ### 🔍 Native Tools
 Built-in `read_file`, `write_file`, `search_files`, `patch`, `shell`, and `browser` tools. All gated by a unified security layer (`dangerous` config) — classify operations as `allow` / `deny` / `prompt` per risk class. No third-party dependencies. [docs/SECURITY.md](docs/SECURITY.md)
 
+### 🌐 Local Web Search
+`web_search` queries a **self-hosted [SearXNG](https://docs.searxng.org/) metasearch instance** — no cloud search API, no keys. Returns ranked results (title, url, snippet) the agent then fetches with `browser` / `http_batch`; results are wrapped as untrusted content and gated as `network_egress`. The Docker Compose setup runs a SearXNG sidecar and enables it out of the box; standalone installs point `web_search.base_url` at any SearXNG instance. [docs/CHEATSHEET.md](docs/CHEATSHEET.md#web-search)
+
 ---
 
 ## Quick Start

cmd/odek/injection_hardening_test.go

@@ -9,7 +9,6 @@ import (
 	"testing"
 
 	"github.com/BackendStack21/odek"
-	"github.com/BackendStack21/odek/internal/config"
 	"github.com/BackendStack21/odek/internal/danger"
 )
 
@@ -244,7 +243,7 @@ func TestBuiltinTools_SessionSearchWrappedAsUntrusted(t *testing.T) {
 	store, cleanup := seedSessionStore(t)
 	defer cleanup()
 
-	tools := builtinTools(danger.DangerousConfig{}, nil, nil, 4, "", config.TranscriptionConfig{}, config.VisionConfig{}, store)
+	tools := builtinTools(danger.DangerousConfig{}, nil, nil, 4, "", toolConfig{}, store)
 
 	var ss odek.Tool
 	for _, tool := range tools {

cmd/odek/main.go

@@ -779,7 +779,7 @@ func run(args []string) error {
 
 	// Sandbox setup
 	var sandboxCleanup func() error
-	tools := builtinTools(resolved.Dangerous, sm, nil, resolved.MaxConcurrency, resolved.APIKey, resolved.Transcription, resolved.Vision, nil)
+	tools := builtinTools(resolved.Dangerous, sm, nil, resolved.MaxConcurrency, resolved.APIKey, toolConfig{Transcription: resolved.Transcription, Vision: resolved.Vision, WebSearch: resolved.WebSearch}, nil)
 
 	// MCP server tools
 	var mcpCleanup func()
@@ -1054,7 +1054,17 @@ func setupSandbox(tools []odek.Tool, cfg sandboxConfig) (containerName string, c
 	return containerName, cleanup, nil
 }
 
-func builtinTools(dc danger.DangerousConfig, sm *skills.SkillManager, approver danger.Approver, maxConcurrency int, apiKey string, tc config.TranscriptionConfig, vc config.VisionConfig, store *session.Store) []odek.Tool {
+// toolConfig bundles the per-tool configuration sections threaded into
+// builtinTools. Grouping them keeps the builtinTools signature stable as new
+// configurable tools are added (rather than growing a positional parameter
+// per tool).
+type toolConfig struct {
+	Transcription config.TranscriptionConfig
+	Vision        config.VisionConfig
+	WebSearch     config.WebSearchConfig
+}
+
+func builtinTools(dc danger.DangerousConfig, sm *skills.SkillManager, approver danger.Approver, maxConcurrency int, apiKey string, tcfg toolConfig, store *session.Store) []odek.Tool {
 	tools := []odek.Tool{
 		&shellTool{
 			dangerousConfig: dc,
@@ -1088,8 +1098,8 @@ func builtinTools(dc danger.DangerousConfig, sm *skills.SkillManager, approver d
 		&base64Tool{dangerousConfig: dc},
 		&trTool{dangerousConfig: dc},
 		&wordCountTool{dangerousConfig: dc},
-		newTranscribeTool(dc, tc),
-		newVisionTool(dc, vc),
+		newTranscribeTool(dc, tcfg.Transcription),
+		newVisionTool(dc, tcfg.Vision),
 		// session_search returns content from arbitrary past sessions —
 		// including sessions that ingested untrusted content. That path
 		// otherwise bypasses the memory taint gate and the audit log, so
@@ -1098,6 +1108,13 @@ func builtinTools(dc danger.DangerousConfig, sm *skills.SkillManager, approver d
 		newBrowserTool(dc),
 	}
 
+	// web_search is registered only when a SearXNG backend is configured —
+	// without a base_url there is no instance to query, so the tool would just
+	// confuse the agent. The Docker compose setup sets this automatically.
+	if tcfg.WebSearch.BaseURL != "" {
+		tools = append(tools, newWebSearchTool(dc, tcfg.WebSearch))
+	}
+
 	if sm != nil {
 		tools = append(tools,
 			&skills.SkillLoadTool{Manager: sm},
@@ -1599,7 +1616,7 @@ func continueCmd(args []string) error {
 			"./.odek/skills",
 		)
 	}
-	tools := builtinTools(resolved.Dangerous, sm, nil, resolved.MaxConcurrency, resolved.APIKey, resolved.Transcription, resolved.Vision, store)
+	tools := builtinTools(resolved.Dangerous, sm, nil, resolved.MaxConcurrency, resolved.APIKey, toolConfig{Transcription: resolved.Transcription, Vision: resolved.Vision, WebSearch: resolved.WebSearch}, store)
 	var sandboxCleanup func() error
 
 	// MCP server tools

cmd/odek/main_test.go

@@ -203,7 +203,7 @@ func TestRun_NoAPIKey(t *testing.T) {
 }
 
 func TestBuiltinTools(t *testing.T) {
-	tools := builtinTools(danger.DangerousConfig{}, nil, nil, 3, "", config.TranscriptionConfig{}, config.VisionConfig{}, nil)
+	tools := builtinTools(danger.DangerousConfig{}, nil, nil, 3, "", toolConfig{}, nil)
 	if len(tools) == 0 {
 		t.Fatal("builtinTools() returned empty slice")
 	}

cmd/odek/mcp.go

@@ -73,7 +73,7 @@ Flags:
 	}
 
 	// Build tools
-	toolSet := builtinTools(resolved.Dangerous, sm, nil, resolved.MaxConcurrency, resolved.APIKey, config.TranscriptionConfig{}, config.VisionConfig{}, nil)
+	toolSet := builtinTools(resolved.Dangerous, sm, nil, resolved.MaxConcurrency, resolved.APIKey, toolConfig{WebSearch: resolved.WebSearch}, nil)
 
 	// MCP server tools — connect and discover before sandbox
 	var mcpCleanup func()

cmd/odek/repl.go

@@ -77,7 +77,7 @@ func replCmd(args []string) error {
 			"./.odek/skills",
 		)
 	}
-	tools := builtinTools(resolved.Dangerous, sm, nil, resolved.MaxConcurrency, resolved.APIKey, config.TranscriptionConfig{}, config.VisionConfig{}, nil)
+	tools := builtinTools(resolved.Dangerous, sm, nil, resolved.MaxConcurrency, resolved.APIKey, toolConfig{WebSearch: resolved.WebSearch}, nil)
 	var sandboxCleanup func() error
 
 	// MCP server tools

cmd/odek/schedule.go

@@ -570,7 +570,7 @@ func runTaskHeadless(ctx context.Context, resolved config.ResolvedConfig, system
 		resolved.Dangerous.NonInteractive = &deny
 	}
 
-	tools := builtinTools(resolved.Dangerous, nil, nil, resolved.MaxConcurrency, resolved.APIKey, resolved.Transcription, resolved.Vision, nil)
+	tools := builtinTools(resolved.Dangerous, nil, nil, resolved.MaxConcurrency, resolved.APIKey, toolConfig{Transcription: resolved.Transcription, Vision: resolved.Vision, WebSearch: resolved.WebSearch}, nil)
 	tools = append(tools, mcpTools...)
 
 	// Capture cumulative token usage from the final iteration so the Runner

cmd/odek/serve.go

@@ -267,7 +267,7 @@ func newServeAgent(resolved config.ResolvedConfig, system string, sendFn func(v
 	approver := newWSApprover(sendFn)
 	resolved.Dangerous.Approver = approver
 
-	tools := builtinTools(resolved.Dangerous, sm, approver, resolved.MaxConcurrency, resolved.APIKey, config.TranscriptionConfig{}, config.VisionConfig{}, nil)
+	tools := builtinTools(resolved.Dangerous, sm, approver, resolved.MaxConcurrency, resolved.APIKey, toolConfig{WebSearch: resolved.WebSearch}, nil)
 
 	// Find the delegateTasksTool to wire up sub-agent log streaming
 	var subagentTool *delegateTasksTool

cmd/odek/subagent.go

@@ -291,7 +291,7 @@ func subagentCmd(args []string) error {
 			"./.odek/skills",
 		)
 	}
-	tools := builtinTools(resolved.Dangerous, sm, nil, resolved.MaxConcurrency, resolved.APIKey, config.TranscriptionConfig{}, config.VisionConfig{}, nil)
+	tools := builtinTools(resolved.Dangerous, sm, nil, resolved.MaxConcurrency, resolved.APIKey, toolConfig{WebSearch: resolved.WebSearch}, nil)
 	var sandboxCleanup func() error
 
 	// MCP server tools

cmd/odek/subagent_contract_test.go

@@ -12,7 +12,6 @@ import (
 	"time"
 
 	"github.com/BackendStack21/odek"
-	"github.com/BackendStack21/odek/internal/config"
 	"github.com/BackendStack21/odek/internal/danger"
 	"github.com/BackendStack21/odek/internal/llm"
 )
@@ -320,7 +319,7 @@ func TestSubagent_ExitCodeThree(t *testing.T) {
 // ── 4. delegate_tasks Tool Schema ───────────────────────────────────
 
 func TestDelegateTasksTool_Exists(t *testing.T) {
-	tools := builtinTools(danger.DangerousConfig{}, nil, nil, 3, "", config.TranscriptionConfig{}, config.VisionConfig{}, nil)
+	tools := builtinTools(danger.DangerousConfig{}, nil, nil, 3, "", toolConfig{}, nil)
 	if len(tools) == 0 {
 		t.Fatal("builtinTools() returned empty slice")
 	}
@@ -338,7 +337,7 @@ func TestDelegateTasksTool_Exists(t *testing.T) {
 }
 
 func TestDelegateTasksTool_HasSchema(t *testing.T) {
-	tools := builtinTools(danger.DangerousConfig{}, nil, nil, 3, "", config.TranscriptionConfig{}, config.VisionConfig{}, nil)
+	tools := builtinTools(danger.DangerousConfig{}, nil, nil, 3, "", toolConfig{}, nil)
 
 	var tool odek.Tool
 	for _, t2 := range tools {
@@ -432,7 +431,7 @@ func TestDelegateTasksTool_HasSchema(t *testing.T) {
 }
 
 func TestDelegateTasksTool_Description(t *testing.T) {
-	tools := builtinTools(danger.DangerousConfig{}, nil, nil, 3, "", config.TranscriptionConfig{}, config.VisionConfig{}, nil)
+	tools := builtinTools(danger.DangerousConfig{}, nil, nil, 3, "", toolConfig{}, nil)
 
 	var tool odek.Tool
 	for _, t2 := range tools {