[reddynitish]

Problem and change

Closes #7564.

Applications currently need to override private methods to customize the retry instructions sent to a model. Add the maintainer-approved reflection_guidance and retry_exceeded_guidance options, accepting text or synchronous/asynchronous providers, plus public async build_reflection_guidance and build_retry_exceeded_guidance hooks.

Providers receive a frozen ToolReflectionContext with tool arguments, the error and its formatted details, retry count/limit and ToolContext. Empty guidance is supported; invalid provider results raise TypeError and provider exceptions propagate. Providers run outside the failure-tracker lock. Existing defaults and ToolFailureResponse fields remain unchanged, including the capped retry count on the exhausted path.

Companion documentation: google/adk-docs#2443 (draft until this implementation lands).

Testing plan and results

• Existing plugin module on unchanged main: 25 passed.
• Expanded plugin module on Python 3.11, 3.12, 3.13 and 3.14: 42 passed each. Coverage includes text/sync/async providers, context values, subclass hooks, empty strings, invalid results, provider errors, zero/exhausted retries, throwing mode, custom error extraction and awaiting outside the tracker lock.
• Entire plugin suite: 1,424 passed, 2 skipped.
• Compared 12 default response dictionaries against the unchanged implementation: exact equality, including guidance text and metadata.
• Changed-module mypy: no issues found.
• Pre-commit and git diff --check: passed.
• Manual offline Runner check: a scripted model called a failing lookup tool twice with max_retries=1. The first FunctionResponse carried custom async guidance; the second carried custom exhausted guidance. Both retained ValueError, ticket unavailable, retry count 1 and the plugin-owned response type:

reflection_guidance: Check lookup parameters before retrying.
reflection_guidance: Ask the user what to do next.
PASS: Runner delivered async retry guidance and final guidance with unchanged failure metadata.

The Runner check used the actual LlmAgent, tool and plugin flow with the existing MockModel/TestInMemoryRunner test helpers; no live model requests.

• Full tox -p auto completed:

Python	Passed	Failed
3.11	20,219	1
3.12	20,210	1
3.13	20,210	1
3.14	20,211	1

The full suites are not green: every version fails only tests/unittests/integrations/vmaas/test_agent_engine_environment.py::test_reading_directory_raises (DID NOT RAISE OSError). The same test fails on all four versions in a separate, clean checkout of unchanged base commit e2dbc0f, using the same dependencies. That unrelated directory-read test is left outside this focused plugin change.

Code/tests were drafted with Gemini CLI assistance, then reviewed, simplified and independently validated with Codex assistance.