feature: harden dynamic tool retrieval rollout with priors, validation, testing, and execution plan

Background

History-aware retrieval can work from per-request context alone, but quality may vary during cold start or after restarts if no reusable transition priors exist. Lightweight persistence provides continuity and helps stabilize ranking when recent context is sparse. At the same time, new retrieval configuration knobs increase misconfiguration risk unless validation, examples, and docs are shipped with the feature. Finally, behavior-visible tool-selection changes require a full validation ladder and explicit rollout gates to prevent regressions. This consolidated issue combines persistence, contract hardening, validation, testing, and rollout coordination so the workstream can land as one operationally safe milestone.

Describe the feature

Implement an end-to-end hardening package for dynamic tool retrieval:

• add optional lightweight persistence for tool transition priors keyed by decision/category:
• maintain counts for observed next-tool transitions
• expose read API for retriever scoring
• include bounds/TTL and safe startup defaults
• update validation and examples for dynamic retrieval fields:
• strict validation for strategy and weight ranges
• decision plugin examples under config/plugin/tools/
• docs updates for config reference and tutorial pages
• add validation across unit, integration, and E2E layers:
• unit tests for strategy scoring and fallback behavior
• extproc integration tests for tool mutation path
• E2E profile updates for behavior-visible routing/tool-selection changes
• include a rollout plan in the issue body with explicit ordering and risk controls:
• contract/config validation complete before persistence rollout
• persistence behind safe default and feature toggle
• runtime and E2E gates required before enabling broadly

Default behavior must remain functional without persisted priors enabled.

Why do you need this feature?

We need one coordinated issue to reduce rollout risk: improve cold-start stability via persisted priors, prevent config drift via strict validation/docs, and guarantee behavior through unit/integration/E2E validation.

Additional context

Keep storage lifecycle ownership clear and avoid coupling retrieval logic to backend-specific code. Track metrics deltas such as selected-tool count, retrieval latency, and tool-call success rate in benchmark/E2E outputs.