chore(structure): split hook modules into role-specific files

[RonnyPfannschmidt]

Written by Claude Opus 5 via Claude Code for the pluggy maintainers; I prompted it, it did the work, I read it.

Merge PR — step 1 of 7.

This PR targets main and is the bottom of the stack, so it is ready to merge on its own. Review discussion happens in RonnyPfannschmidt#6.

Step	Branch	Review (downstream)	Merge (upstream)
1	refactor/split-hook-modules	RonnyPfannschmidt#6	#703 ←
2	refactor/configuration-objects	RonnyPfannschmidt#5	#704
3	refactor/markers-attach-config	RonnyPfannschmidt#7	#706
4	refactor/hookimpl-wrapper-types	RonnyPfannschmidt#8	#707
5	refactor/hookcaller-and-execution	RonnyPfannschmidt#9	#708
6	refactor/project-spec	RonnyPfannschmidt#10	#709
7	refactor/async-submitter	RonnyPfannschmidt#11	#710

Step 1 of 7 — bottom of the stack, targets main, mergeable on its own.

#703 → #704 → #706 → #707 → #708 → #709 → #710

Per-step review discussion lives on the fork: #6 (this step), then #5, #7, #8, #9, #10, #11.

---

_hooks.py had grown to hold the option types, both markers, HookSpec, HookImpl, and HookCaller at once. This splits it, and _callers.py, along role lines:

module	holds
_config	HookspecOpts, HookimplOpts, normalize_hookimpl_opts
_decorators	HookspecMarker, HookimplMarker, HookSpec, varnames
_impl	HookImpl
_caller	HookCaller, _SubsetHookCaller, HookRelay
_execution	_multicall and the wrapper/teardown helpers

_hooks and _callers stay as re-export shims, so every existing import — including the private ones pytest and others reach for — keeps working.

Pure code movement, no behavior change. The point is to give the later steps (typed config objects, CompletionHook, a Protocol HookCaller) somewhere to land without each one also being a reorganization.

Rebased onto current main, so it carries the subset_hook_caller fix from #695 and the stacklevel fix from #727 into the modules those moved to.

[bluetech]

The change looks OK to me. Personally I don't much like too many files but it's fine if you want to split some more.

Two comments:

• The _config.py file seems like not really an independent thing to me. I'd merge it with _decorators.py, such that the specs & markers are together.
• I'd rename _implementation.py to _impl.py, that would make it clearer it refers to hook impl and some other "implementation".

Also carries design/: the writeups for all seven steps, so the rationale sits next to the code rather than in the PR log.

I would very much prefer if we don't commit these. If a human wants to write a coherent architecture document that'd be cool, but I think huge amounts of AI-generated texts have no place in the repo, as long as humans are working on it at least.

[RonnyPfannschmidt]

i dropped the spec and decided against merging the files as followups add to it