fix: add client-side validation for shell tool allowlist network policy

[giulio-leone]

Summary

This is a proactive security improvement, not a bug fix — there is no linked issue. Users configuring the shell tool's allowed_domains network policy can accidentally pass malformed entries (protocol prefixes, URL paths, empty lists) that silently produce an opaque server-side 500 error. This PR adds client-side validation to catch these mistakes early with clear error messages, and adds serialization regression tests to lock down the correct wire format.

Addresses #2920 (related server-side regression context).

Changes

1. Client-side validation (src/openai/lib/_validation.py) — validates allowed_domains entries before the request is sent. Raises a clear ValueError for:

   • Empty domain lists (minItems: 1 in the spec)
   • Domains with protocol prefixes (http://example.com → suggests example.com)
   • Domains with URL paths (example.com/api)
   • Empty/whitespace-only strings

2. Serialization regression tests (tests/test_shell_tool_allowlist.py, 24 tests) — prove the library sends the correct JSON for:

   • Allowlist with single/multiple domains
   • Allowlist with domain_secrets
   • Disabled network policy
   • Shell tool without environment
   • Full maybe_transform round-trip

The validation is wired into the existing _make_tools() helper so it runs for both sync and async responses.create() calls.

Why This Matters

Without this validation, users who misconfigure their shell tool allowlist get a cryptic 500 error from the API with no indication of what they did wrong. The client-side check provides an actionable error message before the request is ever sent, reducing debugging time and preventing accidental command exposure through misconfigured allowlists.

Workaround for the server-side issue

Until the API regression is resolved, users can work around it by omitting the network_policy field or setting it to {"type": "disabled"}.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e487c2419b

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Preserve iterable tools before validating

_make_tools accepts Iterable[ParseableToolParam], but validate_tools(tools) consumes that iterable before the conversion loop runs; when callers pass a one-shot iterator (for example, a generator), the subsequent for tool in tools loop is empty and the request is sent without any tools. This is a behavior regression introduced by the validation call and can silently disable tool execution.

Useful? React with 👍 / 👎.

[giulio-leone]

Fixed in c7fc0a3 — tools is now materialised to a list before validate_tools() runs, so one-shot iterators are preserved for the conversion loop.

[chatgpt-codex-connector]

Reject trailing slash in allowlist domains

The path regex r"/." fails to match domains ending in a bare slash (for example "example.com/"), so these malformed entries pass client-side validation even though they are not bare domains. In that case users still hit the opaque server error this new validation is intended to prevent.

Useful? React with 👍 / 👎.

[giulio-leone]

Friendly ping — CI is green, tests pass, rebased on latest. Ready for review whenever convenient. Happy to address any feedback. 🙏