feat(tools): add web_search provider alias routing with safe fallback

[Jacobinwwey]

Summary

Describe this PR in 2-5 bullets:

• Base branch target (master for all contributions): master
• Problem: web_search provider routing accepted only a narrow set of exact strings and returned a hard error for unknown values, making alias drift or minor config typos fail the tool call.
• Why it matters: Search capability should remain resilient when provider names vary by alias or legacy config conventions.
• What changed: Added a dedicated provider-routing module with canonical routes (duckduckgo, brave), alias normalization (including ddg, duck-duck-go, duck_duck_go, brave-search, brave_search, plus default/empty), and safe fallback to DuckDuckGo with warning telemetry when provider is unknown.
• What did not change (scope boundary): No new search engine integrations, no network/security policy changes, and no change to Brave API-key requirements.

Label Snapshot (required)

• Risk label (risk: low|medium|high): risk: low
• Size label (size: XS|S|M|L|XL, auto-managed/read-only): size: S (expected, auto-managed)
• Scope labels (core|agent|channel|config|cron|daemon|doctor|gateway|health|heartbeat|integration|memory|observability|onboard|provider|runtime|security|service|skillforge|skills|tool|tunnel|docs|dependencies|ci|tests|scripts|dev, comma-separated): tool, provider, tests
• Module labels (: , for example channel: telegram, provider: kimi, tool: shell): tool: web_search
• Contributor tier label (trusted contributor|experienced contributor|principal contributor|distinguished contributor, auto-managed/read-only; author merged PRs >=5/10/20/50): auto-managed
• If any auto-label is incorrect, note requested correction: None

Change Metadata

• Change type (bug|feature|refactor|docs|security|chore): feature
• Primary scope (runtime|provider|channel|memory|security|ci|docs|multi): provider

Linked Issue

• Closes #N/A
• Related #N/A
• Depends on #N/A
• Supersedes #N/A

Supersede Attribution (required when Supersedes # is used)

• Superseded PRs + authors (# by @, one per line): N/A
• Integrated scope by source PR (what was materially carried forward): N/A
• Co-authored-by trailers added for materially incorporated contributors? (Yes/No): N/A
• If No, explain why (for example: inspiration-only, no direct code/design carry-over): N/A
• Trailer format check (separate lines, no escaped \n): (Pass/Fail): N/A

Validation Evidence (required)

Commands and result summary:

cargo fmt --all -- --check
cargo test --quiet resolve_unknown_provider_falls_back_to_default
cargo test --quiet test_execute_brave_without_api_key

• Evidence provided (test/log/trace/screenshot/perf):
  • cargo fmt --all -- --check passed.
  • Provider-resolution fallback test passed.
  • Brave-no-key error-path regression test passed.
• If any command is intentionally skipped, explain why:
  • cargo clippy --all-targets -- -D warnings was not run in this cycle.
  • Full cargo test matrix was not run in this cycle; targeted tests were run for changed behavior.

Security Impact (required)

• New permissions/capabilities? (Yes/No): No
• New external network calls? (Yes/No): No
• Secrets/tokens handling changed? (Yes/No): No
• File system access scope changed? (Yes/No): No
• If any Yes, describe risk and mitigation: N/A

Privacy and Data Hygiene (required)

• Data-hygiene status (pass|needs-follow-up): pass
• Redaction/anonymization notes: No expansion of data collection or sensitive logging; only provider-name routing behavior changed.
• Neutral wording confirmation (use ZeroClaw/project-native labels if identity-like wording is needed): Confirmed

Compatibility / Migration

• Backward compatible? (Yes/No): Yes
• Config/env changes? (Yes/No): No
• Migration needed? (Yes/No): No
• If yes, exact upgrade steps: N/A

i18n Follow-Through (required when docs or user-facing wording changes)

• i18n follow-through triggered? (Yes/No): No
• If Yes, locale navigation parity updated in README*, docs/README*, and docs/SUMMARY.md for supported locales (en, zh-CN, ja, ru, fr, vi)? (Yes/No): N/A
• If Yes, localized runtime-contract docs updated where equivalents exist (minimum for fr/vi: commands-reference, config-reference, troubleshooting)? (Yes/No/N.A.): N/A
• If Yes, Vietnamese canonical docs under docs/i18n/vi/** synced and compatibility shims under docs/*.vi.md validated? (Yes/No/N.A.): N/A
• If any No/N.A., link follow-up issue/PR and explain scope decision: Code-only behavior update; no docs/runtime copy changes.

Human Verification (required)

What was personally validated beyond CI:

• Verified scenarios:
  • Provider aliases route to canonical engines as expected.
  • Unknown provider no longer hard-fails tool execution and falls back to DuckDuckGo.
  • Existing Brave missing-key path remains intact.
• Edge cases checked:
  • Unknown provider string fallback path.
  • Alias-based routing for DuckDuckGo and Brave.
• What was not verified:
  • End-to-end external search behavior under live provider latency/network variance.
  • Full repository regression suite in this cycle.

Side Effects / Blast Radius (required)

• Affected subsystems/workflows: web search provider resolution path (web_search_tool)
• Potential unintended effects: Misconfigured provider names now degrade to DuckDuckGo instead of failing fast, which may hide configuration typos unless warnings are monitored.
• Guardrails/monitoring for early detection: Warning log emitted on fallback with original provider value and selected canonical fallback.

Agent Collaboration Notes (recommended)

• Agent tools used (if any): shell (git, gh, cargo test, cargo fmt)
• Workflow/plan summary (if any): Isolated PR branch from origin/master, validated targeted regressions, applied template-compliant PR description.
• Verification focus: provider alias routing correctness and unknown-provider fallback behavior
• Confirmation: naming + architecture boundaries followed (AGENTS.md + CONTRIBUTING.md): Yes

Rollback Plan (required)

• Fast rollback command/path: git revert a558eadd
• Feature flags or config toggles (if any): N/A
• Observable failure symptoms:
  • Unexpected DuckDuckGo routing when a non-supported provider value is configured.
  • Missing warning logs for fallback path.

Risks and Mitigations

List real risks in this PR (or write None).

• Risk: Fallback behavior may mask provider-name typos in configuration.
  • Mitigation: Explicit warning is emitted on unknown provider fallback; canonical provider is included in the warning.

[theonlyhennygod]

LGTM. Clean extraction of provider alias routing into a dedicated module with safe fallback to DuckDuckGo for unknown providers instead of hard error.