How it happened to me: I went afk and someone else dug a deep hole beneath me, dropped me into it, covered it up.

How it could happen more naturally: I use cave collapse, but there are other mods that could theoretically entrap you with the idea that you're always otherwise able to break blocks.

I think that the demon should be made to clip through solid surfaces. Maybe apply a thick overlay and reduce movement to discourage doing it unless necessary. But of course I don't care much the resolution, more that I cant get stuck anymore!

Being able to move through blocks with some resistance is an interesting idea. I can try implementing it, though it would require quite a bit of messing around with collisions.
With that said, there should be an enderman spawning next to you when you get trapped. Was the hole too small for it to spawn ?

It was a 1 block hole, so yeah, no room :/

Oh, version 1.4.0 adds the ability for incorporeal players to move through walls =)