[5660] chore(sdk): validate reserved tool names before secret lookup and adapter calls

[MarceloAdan73]

Summary

When a tool config declares a custom tool whose name collides with a Pi built-in, the SDK's ToolResolver rejects it with ReservedToolNameError — but only after resolving secrets and calling the workflow, platform, and gateway adapters. A reserved-named code tool with a missing secret today surfaces MissingToolSecretError (wrong problem), and reserved-named gateway/reference/platform tools still do secret lookups and network calls before being refused (wasted work for a payload that will always be rejected).

This PR moves the reserved/duplicate declared-name validation to the top of resolve(), before any secret lookup or adapter call, while keeping the final _validate_unique_names(tool_specs) pass to cover adapter-produced spec names. Behavior for valid payloads is identical — only error precedence changes.

Demo

Before (adapter invoked, wrong error) vs after (fails fast, zero adapter calls):

Symptom

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 always happened before any spec left resolve(), so no reserved name reached the runner; this is error-precedence and wasted-work hygiene, not a bypass.

Change

Declared custom tool names are now validated up front, before any secret lookup or adapter resolution:

• Added _validate_declared_config_names() at the top of resolve(), raising ReservedToolNameError (reserved built-in names) or DuplicateToolNameError (duplicates among declared names) before any secret or adapter work.
• Factored the shared checks into _check_tool_name() so both the new up-front pass and the final _validate_unique_names(tool_specs) use the same logic (no duplication).
• The final _validate_unique_names() call stays unchanged, still covering adapter-produced spec names (e.g. a gateway integration__action fallback) that the up-front pass cannot see.
• Behavior for valid payloads is identical; only the error precedence moves earlier.

Before / After

Payload	Before	After
code tool named read with missing secret	MissingToolSecretError (wrong problem)	ReservedToolNameError (fail fast)
Gateway tool with reserved name	Adapter invoked, rejection at the end	ReservedToolNameError before any adapter call

Tests

• test_reserved_name_fails_fast_before_secret_lookup_and_adapter_calls: reserved-named code tool with a missing secret raises ReservedToolNameError (not MissingToolSecretError), and the secret provider and gateway adapter are never invoked.
• test_reserved_gateway_name_fails_before_adapter_call: reserved gateway name is rejected before the adapter runs.
• Sanity-checked that both new tests fail when the up-front validation is removed (not vacuous).
• Full SDK unit suite: 1831 passed, 1 failed / 40 errors (both pre-existing environment gaps on Windows: a test needing the TS runner via pnpm and the agenta distribution not installed in the local venv; test_resolver.py 25/25 green). Ruff 0.15.12 (CI version) and ruff format pass on both files.

AI model used

This change was produced with an AI coding agent (DeepSeek v4 flash, opencode agent) following the step-by-step instructions in this issue. The session: read resolver.py and test_resolver.py, implemented the up-front validation pass factoring the shared name checks, added the two fast-fail tests, ran the targeted tests (25/25), sanity-checked test validity by reverting the fix (both new tests failed, confirming they are not vacuous), restored the fix, ran the full unit suite (only pre-existing environment gaps failed), and verified ruff 0.15.12 + format pass.

Closes #5660

[vercel]

Someone is attempting to deploy a commit to the agenta projects Team on Vercel.

A member of the Team first needs to authorize it.

[CLAassistant]

All committers have signed the CLA.

[github-actions]

✅ Thanks @MarceloAdan73! This PR now meets the contribution requirements and has been reopened. A maintainer will review it soon.

[coderabbitai]

📝 Walkthrough

Summary by CodeRabbit

• Bug Fixes
  • Tool configurations now reject reserved built-in names and duplicate names earlier in validation.
  • Invalid tool names are detected before secret lookups or gateway resolution, providing faster and clearer errors.
  • Automatically generated tool names continue to be validated before use.

Walkthrough

ToolResolver validates declared tool names before secret lookup and adapter resolution. Tests cover reserved code and gateway names. Final validation still checks names produced by adapters.

Changes

Tool name validation

Layer / File(s)	Summary
Shared declared-name validation sdks/python/agenta/sdk/agents/tools/resolver.py	Shared helpers extract declared names and reject reserved built-in names and duplicate declared names. Final validation reuses the helper.
Pre-resolution validation and coverage sdks/python/agenta/sdk/agents/tools/resolver.py, sdks/python/oss/tests/pytest/unit/agents/tools/test_resolver.py	ToolResolver.resolve validates names before secret lookup and adapter calls. Tests verify reserved code and gateway names fail with no downstream calls.

Estimated code review effort: 2 (Simple) | ~15 minutes

Sequence Diagram(s)

sequenceDiagram
  participant ToolResolver
  participant SecretProvider
  participant GatewayAdapter
  ToolResolver->>ToolResolver: Validate declared tool names
  ToolResolver->>SecretProvider: Look up secrets for valid configurations
  ToolResolver->>GatewayAdapter: Resolve valid gateway configurations

Loading

Possibly related PRs

• Agenta-AI/agenta#4893: Both modify resolver.py for platform and gateway tool validation.
• Agenta-AI/agenta#5663: Both address custom names that collide with reserved built-in tools.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The implementation satisfies issue #5660 by validating declared names early and retaining final validation for adapter-produced names.
Out of Scope Changes check	✅ Passed	The code and tests are limited to reserved-name validation, duplicate checks, error precedence, and related resolver behavior.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Title check	✅ Passed	The title clearly summarizes the main change: early validation of reserved tool names before secret lookup and adapter calls.
Description check	✅ Passed	The description directly explains the fail-fast validation change, its rationale, implementation, tests, and preserved behavior.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[mmabrouk]

@all-contributors please add @MarceloAdan73 for code

[allcontributors]

@mmabrouk

I've put up a pull request to add @MarceloAdan73! 🎉

[mmabrouk]

Thanks @MarceloAdan73 ! LGTM