Tell the Python LangGraph Bot's model why a tool call was refused

[kevin9327]

What this changes

When the deployment will not run a tool call from the Python LangGraph Bot (agent-langgraph-agui), /api/agent-tools/call answers with a status and the reason under error: a token it no longer accepts, a token issued to another Bot, or a malformed call (400). The Bot dropped the reason, so its model was told only:

Refused. Tool callback returned HTTP 403.

The model could say a call was refused but not why, and could not correct a call the deployment had named as malformed. The TypeScript LangGraph Bot passes the reason on since #518 (agent-langgraph/src/tool-answer.ts); this is the same reading for the Python one:

Refused. Tool callback returned HTTP 403. That token is not for this Bot.

The reason is read on its own, so a body that is not JSON (a proxy's HTML error page) still reads as Refused. Tool callback returned HTTP 502. rather than falling into the "could not be completed" branch, and a blank error adds nothing. A successful call is untouched.

Where it runs

• New state that outlives a request? None. One more read of a response body already in hand.
• What happens on the second replica? Nothing changes; the Bot process holds no state for this.
• Anything serialised? No.
• Anything fanned out to a browser? No.
• New listener, port, or schedule? No.

Boundary and audit

• Every acting call still goes through the gateway: resolve, decide, audit, then act. The refusal and its mcp.callback_refused row are unchanged; only what the Bot tells its model changes.
• New refusals and new failures each write a row. No new refusals.
• Nothing new is trusted from the client that the server can resolve itself. The text comes from this deployment's own refusal.

Changelog

• A line in CHANGELOG.md under Unreleased.

Proof

New parametrised test in agent-langgraph-agui/tests/test_tool_protocol.py, driven through the real AG-UI endpoint against the file's existing loopback callback server (the fixture can now reply with a chosen body).

Before the fix:

FAILED ...test_http_refusal_tells_the_model_the_deployments_reason[403-...]
FAILED ...test_http_refusal_tells_the_model_the_deployments_reason[400-...]
E       - Refused. Tool callback returned HTTP 400. Tool args must be a JSON object.
E       + Refused. Tool callback returned HTTP 400.
2 failed, 3 passed

(The blank-reason and non-JSON 502 cases already passed and stay as guards.)

After, the whole Bot suite as CI runs it:

python -m pytest agent-langgraph-agui/tests -q
2 failed, 55 passed, 3 skipped

The two failures are test_chatgpt_token_provider_atomic_writer_*, which run docker run and write under /tmp. They fail identically on main on this machine (no Docker), so they are environmental, not this change.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[davidmckayv]

Deep-reviewed clean (validation, no secret leak, fail-closed, agrees with existing layers). CI green.