refactor(protocols): restore Chat/Responses ToolChoice separation invariant

[slin1237]

Summary

Follow-up to #1310. Restores an architectural invariant that was over-pruned in that PR: the `NOTE` explaining that `ResponsesToolChoice` must remain separate from `common::ToolChoice` because Chat Completions has different `Function` wire shape and does not accept Responses-specific variants (`Types`/`Mcp`/`Custom`/`ApplyPatch`/`Shell`).

gemini-code-assist raised this as a medium-priority concern on #1310 after that PR was already merged, flagging that losing this context could let future refactors merge the two enums and silently accept spec-invalid payloads on `/v1/chat/completions`.

Why

The original paragraph in #1310 was dropped as "deliberately" / "PR-body-in-source" prose. But it also carried a real invariant a future reader would miss. Per C2's own PRUNE rule ("shorten without deleting"), the correct outcome is a condensed NOTE that keeps the invariant and drops the audit framing.

What

One 5-line `NOTE:` block added above the `ResponsesToolChoice` derives:

```rust
/// NOTE: kept separate from `common::ToolChoice`. Chat Completions uses
/// a different `Function` wire shape (nested `{"function": {"name": ...}}`)
/// and does not accept the `Types` / `Mcp` / `Custom` / `ApplyPatch` /
/// `Shell` variants; sharing one enum would let `/v1/chat/completions`
/// silently accept spec-invalid payloads.
```

Acceptance

• cargo check -p openai-protocol --lib --tests: green
• cargo clippy -p openai-protocol --lib --tests -- -D warnings: green
• cargo test -p openai-protocol --lib --tests: all pass (18 lib + 41 integration + 94 on responses)
• No semantic changes. Doc comment only.

Refs: #1310

Summary by CodeRabbit

• Documentation
  • Updated internal documentation to clarify design rationale for API response structures.

Note: This release contains no user-visible changes or functional updates.

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 86f13284-cec3-422a-824f-df1ae2209ca4

📥 Commits

Reviewing files that changed from the base of the PR and between 3f36c80 and 8e9fd79.

📒 Files selected for processing (1)

• crates/protocols/src/responses.rs

---

📝 Walkthrough

Walkthrough

A documentation note was added to ResponsesToolChoice clarifying why it is intentionally kept separate from common::ToolChoice. The note explains that Chat Completions uses a different nested Function wire shape and does not accept certain ResponsesToolChoice variants, preventing spec-invalid payloads.

Changes

Cohort / File(s)	Summary
Documentation Note crates/protocols/src/responses.rs	Added clarification documentation to ResponsesToolChoice explaining the intentional separation from common::ToolChoice due to different wire shapes and accepted variant differences in Chat Completions API.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~2 minutes

Possibly related PRs

• feat(responses): add mcp approval items to protocols and routers #491 — Introduces MCP approval variants and router checks in protocols/src/responses.rs that enforce the boundaries documented in this PR's note.
• feat(protocols): implement P7 ToolChoice variant coverage #1276 — Covers ResponsesToolChoice introduction and its validation logic that the documentation clarifies.

Suggested labels

protocols

Suggested reviewers

• CatherineSue
• key4ng

Poem

🐰 A note, so clear, now marks the way,
Why variants part, they'll always stay,
No wire shapes mixed, no specs defied,
Just careful words to be our guide!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: restoring a documentation note that clarifies the architectural invariant requiring Chat/Responses ToolChoice separation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch refactor/audit-c2-followup

---

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

[claude]

Documentation-only change: adds a well-written NOTE explaining why ResponsesToolChoice is kept separate from common::ToolChoice. Verified the claims are accurate against both enums. No issues found.