fix(responses): reject undeclared routed tool calls

[Ingwannu]

Summary

• retain the exact request-visible tool-name set alongside the existing namespace/custom-tool bridge maps
• fail streaming and non-streaming routed turns before emitting a client tool item when the provider invents an undeclared name
• keep exec -> tools.apply_patch(...) as the Code Mode path instead of guessing an automatic conversion for top-level apply_patch
• record the declared-tool membership decision in the transport architecture document

Closes #1544

Verification

bun test tests/responses-parser.test.ts tests/responses-stream-tool-events.test.ts tests/bridge.test.ts
bun run typecheck
bun run privacy:scan
git diff --check

Focused result: 87 pass / 0 fail. Typecheck and privacy scan are green.

Checklist

• Streaming undeclared calls fail with an actionable compatibility error.
• Non-streaming undeclared calls fail with the same contract.
• Declared function, namespace, custom, and tool-search mappings remain covered.
• No automatic executable tool conversion is introduced.

Summary by CodeRabbit

• Bug Fixes
  • Added validation to reject tool calls for names not declared in the request.
  • Streaming responses now fail immediately without emitting executable tool events.
  • Non-streaming responses report a clear compatibility error with failed status and no output.
• Documentation
  • Documented fail-closed handling for undeclared tool names across response modes.
• Tests
  • Added coverage for undeclared tools, allowed tools, filtered selections, tool search, and disabled tool choices.

[github-actions]

✅ Deterministic PR hygiene checks passed.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: b5ff6fd5-88a5-4499-9bfe-7d1d793007b1

📥 Commits

Reviewing files that changed from the base of the PR and between 872c526 and b2c33e9.

📒 Files selected for processing (7)

• src/bridge.ts
• src/server/responses/collaboration.ts
• src/server/responses/core.ts
• structure/04_transports-and-sidecars.md
• tests/bridge.test.ts
• tests/responses-parser.test.ts
• tests/responses-stream-tool-events.test.ts

---

📝 Walkthrough

Walkthrough

The Responses bridge now receives a request-visible tool-name allowlist. It rejects undeclared provider tool calls in streaming and batch responses. Tool selection builds the allowlist, and regression tests cover catalog construction and failure behavior.

Changes

Responses tool validation

Layer / File(s)	Summary
Build declared tool catalog src/server/responses/collaboration.ts, tests/responses-parser.test.ts	buildToolBridgeMaps records authorized wire names from toolChoice, including namespace, custom, tool-search, and "none" cases.
Propagate declared tool names src/server/responses/core.ts	Run-turn and adapter paths pass declaredToolNames to streaming and non-streaming Responses builders.
Reject undeclared tool calls src/bridge.ts, tests/bridge.test.ts, tests/responses-stream-tool-events.test.ts, structure/04_transports-and-sidecars.md	Streaming calls emit response.failed without output or completion events. Batch calls record an upstream error for final failure handling. The decision log documents this behavior.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Mergeability Score: ⚪ Minimal · up to b2c33

The PR rejects undeclared routed tool calls while preserving declared tool mappings and the existing Code Mode path; no actionable merge-blocking risk remains after normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant buildToolBridgeMaps
  participant ResponsesCore
  participant ResponsesBridge
  Client->>buildToolBridgeMaps: provide toolChoice
  buildToolBridgeMaps->>ResponsesCore: return declaredToolNames
  ResponsesCore->>ResponsesBridge: pass declaredToolNames and provider events
  ResponsesBridge->>ResponsesBridge: validate emitted tool name
  ResponsesBridge-->>Client: emit response.failed or final batch failure

Loading

Possibly related PRs

• lidge-jun/opencodex#1382: Both changes use buildToolBridgeMaps to enforce tool selection.
• lidge-jun/opencodex#1531: Both changes add fail-closed validation for invalid provider-emitted tool names.
• lidge-jun/opencodex#1361: Both changes modify Responses tool-call translation and validation paths.

Suggested labels: review-ready

Suggested reviewers: lidge-jun, wibias

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: rejecting routed tool calls that are not declared by the request.
Linked Issues check	✅ Passed	The changes satisfy issue #1544 by rejecting undeclared calls in streaming and non-streaming flows while preserving declared tool mappings and Code Mode paths.
Out of Scope Changes check	✅ Passed	All code, tests, and documentation changes directly support declared-tool validation and the requirements in issue #1544.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch agent/fix-1544-undeclared-tools

---

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.}

[Wibias]

No code blocker from my review. The request-visible declared-tool set is derived from the existing toolChoice-filtered catalog, and both streaming and non-streaming paths fail closed before an undeclared tool becomes client-executable. Keeping exec -> tools.apply_patch(...) as the supported Code Mode path instead of guessing a translation is the right boundary for #1544.

Please rebase onto current dev and rerun CI; if that remains green, this is good to merge.