fix: #781 replace assertion in handoff() with UserError

[0xSudoSSH]

Summary

Replace tautological assertion in handoff() with proper UserError validation.

Two problems with the original assertion:

1. Tautological logic — (X) or not (X) is always True, so the assertion never fires and enforces nothing.

2. Incorrect error message — The message says "You must provide either both on_handoff and input_type, or neither", but on_handoff without input_type is a valid usage (simple callback that takes only context). The only invalid combination is input_type without on_handoff, since there would be no callback to receive the parsed input.

Before (tautology — never fires):

assert (on_handoff and input_type) or not (on_handoff and input_type), (
    "You must provide either both on_input and input_type, or neither"
)

After (correct validation):

if input_type is not None and on_handoff is None:
    raise UserError("input_type requires on_handoff to be provided")

Valid combinations:

on_handoff	input_type	Valid?
None	None	✅ No callback
Provided (1 arg)	None	✅ Simple callback, context only
Provided (2 args)	Provided	✅ Typed callback with parsed input
None	Provided	❌ No callback to receive the parsed input — caught by this fix

Note: downstream checks at lines 259–272 already catch most misuse (e.g., assert callable(on_handoff) and signature length validation), so the tautological assertion was effectively dead code. This fix replaces it with a clear, early validation that produces a helpful error message.

Test plan

• Added test_input_type_without_on_handoff_raises_error to verify the fix
• All 29 existing handoff tests pass (tests/test_handoff_tool.py, tests/test_handoff_prompt.py, tests/test_handoff_history_duplication.py)
• make format, make lint, make typecheck — all pass

Issue number

Closes #781

Checks

• I've added new tests (if relevant)
• I've added/updated the relevant documentation
• I've run make lint and make format
• I've made sure tests pass

[seratch]

Thanks for the fix. The direction looks good to me, especially because it brings regular handoff() closer to the existing Realtime handoff validation.

Before merging, could you please tighten this up by making the user-facing validation consistent across the full path?

Specifically, please replace the adjacent assert callable(on_handoff) with a UserError as well, and apply the same treatment to realtime_handoff() so regular handoffs and Realtime handoffs behave consistently. Since these checks validate user-provided arguments, they should not rely on assert, which can be disabled with Python optimization flags.

It would also be good to use the same error wording in both places, for example:

raise UserError("You must provide on_handoff when input_type is provided")

and a corresponding UserError message for the non-callable case.

[seratch]

Thanks for updating the PR. I will merge other PRs before yours, but no need to rebase this (it triggers a new code review and CI builds for this relatively simple change).

[seratch]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. 🚀

ℹ️ About Codex in GitHub

Your team has set up Codex to 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 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".