(chore) Tool resolver rejects reserved built-in tool names only after secret resolution and adapter calls

[mmabrouk]

When a tool config declares a custom tool whose name collides with a Pi built-in (for example a code tool named read), the SDK's ToolResolver rejects it with ReservedToolNameError. But the check runs last: resolve() first resolves the code tools' secrets and calls the workflow, platform, and gateway adapter resolvers, and only then validates names (_validate_unique_names(tool_specs) at sdks/python/agenta/sdk/agents/tools/resolver.py line 229; the reserved-name check itself is lines 90-96).

What a caller sees today:

• A reserved-named code tool with a missing secret surfaces MissingToolSecretError instead of ReservedToolNameError, pointing the author at the wrong problem.
• A reserved-named gateway, reference, or platform tool still reaches its adapter (secret lookups, network calls) before rejection, so the resolver does work for a payload that will always be refused.

The rejection still always happens before any specs leave resolve(), so no reserved name reaches the runner. This is error-precedence and wasted-work hygiene, not a bypass. Declared custom tool names should be validated up front, before secret lookup and adapter resolution, while the final _validate_unique_names(tool_specs) call stays to cover adapter-produced spec names.

Follow-up from a review comment on #5651: #5651 (comment)

[linear-code]

AGE-4058

[mmabrouk]

🤖 Step-by-step instructions for picking this up (written with coding agents in mind, but they work for humans too):

Steps

1. In sdks/python/agenta/sdk/agents/tools/resolver.py, resolve() (line 120) currently runs secret resolution and the workflow, platform, and gateway adapter resolvers first, and only calls _validate_unique_names(tool_specs) at line 229. Add an up-front validation pass at the top of resolve(), before any secret lookup or adapter call, that checks each declared tool config's name: raise ReservedToolNameError when the name (stripped, lowercased) is in PI_BUILTIN_TOOL_NAMES, and DuplicateToolNameError on duplicates among the declared names. That logic already exists in _validate_unique_names (lines 90-99); factor it so the same checks can run over declared config names as well as final specs, rather than duplicating the code.
2. Keep the final _validate_unique_names(tool_specs) call at line 229 unchanged. It still has to cover spec names produced by the adapters, which the up-front pass cannot see.
3. Change nothing else about resolve(). The behavior for valid payloads must stay identical; only the error precedence for reserved or duplicate declared names moves earlier.
4. Add a test in sdks/python/oss/tests/pytest/unit/agents/tools/test_resolver.py (the reserved-name tests are around line 235) asserting that a reserved-name payload fails fast: for example, a code tool named read that also declares a secret must raise ReservedToolNameError, not MissingToolSecretError, and the secret provider and adapter resolvers must never be invoked. The existing fakes in that file are a good starting point; wrap or spy on the secret provider's get_many and a fake adapter's resolve (a small recording fake or monkeypatch both work) and assert zero calls.

Validation

Run the targeted test file first, then the full SDK suite. Both commands run from the repo root; pass means pytest exits 0 with no failures.

cd sdks/python && uv sync --locked && uv run --no-sync pytest oss/tests/pytest/unit/agents/tools/test_resolver.py -q
cd sdks/python && uv sync --locked && uv run --no-sync python run-tests.py

As a sanity check that the new test is not vacuous, revert the resolve() change locally and confirm the new test fails, then restore the change.

PR requirements

• Title follows the repo convention chore(sdk): <symptom-led title>, and the body follows the repo's PR style: lead with the symptom (the wrong error a caller sees today) and a before/after showing which error is raised for a reserved-name payload with a missing secret.
• The PR description must include a section stating which AI model was used, at what thinking or reasoning budget, and a short summary of the conversation or session that produced the change, so reviewers can calibrate their review.
• Link this issue with Closes #5660.

[MarceloAdan73]

Hi! I'd like to work on this.

I'll follow the step-by-step guide: add an up-front validation pass at the top of
esolve() that checks declared tool names against PI_BUILTIN_TOOL_NAMES (raising ReservedToolNameError) and for duplicates (DuplicateToolNameError), factoring the shared logic out of _validate_unique_names instead of duplicating it. I'll keep the final _validate_unique_names(tool_specs) call at line 229 for adapter-produced names, and add a fast-fail test in est_resolver.py verifying a reserved-named code tool with a missing secret raises ReservedToolNameError (not MissingToolSecretError) and that secret/adapter resolvers are never invoked.

I'll run the targeted test file and the full SDK suite as validation.