The arguments given to $SyntaxHandler are the complete input string and an integer specifying the character position at which the syntax error was detected.
The first character in the string is taken to have position 1.
Any string returned by $SyntaxHandler is used as a new version of the input string, and is fed to Mathematica. If the string does not end with a newline, Mathematica waits for input to complete the line.